MCP server · @cauril/mcp

Expone la API de Cauril como herramientas MCP que un agente descubre y llama. Envuelve @cauril/node; no cambia nada del producto. El dinero no pasa por Cauril y los datos de tarjeta tampoco (SAQ-A).

Esta página es la referencia del paquete (config, CLI y API programática). Para la guía conceptual (conectar en un click desde el dashboard, por qué es seguro), leé Pagos para agentes (MCP).

Correrlo (CLI)

El paquete trae el binario cauril-mcp, que conecta el server por stdio, el transporte que esperan los clientes MCP (Claude Desktop, Cursor, …). Lo normal es que el cliente lo levante con npx y le pases la key por variable de entorno:

mcp config (local)

{
  "mcpServers": {
    "cauril": {
      "command": "npx",
      "args": ["-y", "@cauril/mcp"],
      "env": { "CAURIL_API_KEY": "sk_test_..." }
    }
  }
}

Configuración

Todo se resuelve desde el entorno. La key nunca se loguea ni se imprime.

Variable	Default	Qué hace
`CAURIL_API_KEY`	—	Requerida. Tu secret key (`sk_test_…` o `sk_live_…`).
`CAURIL_BASE_URL`	`https://api.cauril.com`	Override de la URL base.
`CAURIL_MCP_READONLY`	`false`	En `true`, solo se registran las herramientas de lectura.
`CAURIL_MCP_ALLOW_LIVE`	`false`	Necesario para arrancar con una key `sk_live_` (ver abajo).

Con una key sk_live_ el server se niega a arrancar salvo que setees CAURIL_MCP_ALLOW_LIVE=true, así un agente no mueve plata real por accidente mientras desarrollás. En cualquier caso, ninguna herramienta acepta un número de tarjeta crudo: eso es siempre del lado del PSP.

Modo solo-lectura

Para dar acceso sin riesgo, arrancá con CAURIL_MCP_READONLY=true: las herramientas que mueven dinero ni siquiera se registran, así que el agente no puede invocarlas.

JSON

"env": { "CAURIL_API_KEY": "sk_test_...", "CAURIL_MCP_READONLY": "true" }

Herramientas

Lectura (siempre disponibles):

get_payment, list_payments, get_refund, get_customer, list_customers, get_checkout_session, analytics_summary, list_events.

Mutantes (se omiten con CAURIL_MCP_READONLY=true):

create_checkout_session, create_payment, refund_payment, create_customer. Cada una acepta idempotency_key: reusá la misma al reintentar y la operación corre a lo sumo una vez.

Para que un agente cobre, la vía recomendada es create_checkout_session: devuelve una sesión cuyo client_secret tu checkout usa para montar el drop-in, donde el comprador ingresa la tarjeta. Así ningún dato de tarjeta toca al agente. Los montos van como entero en unidad mínima (5000 = $50,00); pasar un decimal se rechaza con un mensaje que le explica al agente cómo corregir.

API programática

Si querés embeber el server (por ejemplo, en un gateway MCP hosteado), el paquete exporta los builders. Los montás sobre cualquier transporte del SDK de MCP.

import { createServerFromEnv, buildServerForApiKey } from "@cauril/mcp";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

// Desde el entorno (CAURIL_API_KEY, etc.). Lanza ConfigError si la config está mal.
const server = createServerFromEnv();
await server.connect(new StdioServerTransport());

// O scopeado a una API key por request (gateway que autentica con el sk_ del caller).
const scoped = buildServerForApiKey(apiKey, {
  baseURL: "https://api.cauril.com",
  readOnly: false,
});

Export	Qué hace
`createServerFromEnv(env?)`	Arma el server desde variables de entorno (aplica el candado de key live). Lanza `ConfigError`.
`buildServerForApiKey(key, opts)`	Server scopeado a una key presentada por request, para un gateway hosteado. Sin candado live.
`buildServer({ cauril, readOnly })`	Builder de bajo nivel sobre una instancia de `@cauril/node`.
`resolveConfig(env)` · `ConfigError`	Resolución/validación de config y su tipo de error.

Hosteado

Si no querés correr nada, Cauril hostea el server en api.cauril.com/mcp: conectás en un click desde el dashboard al crear una API key. La guía de Pagos para agentes tiene la config lista para pegar.