Pagos para agentes (MCP)

La API de pagos que tus agentes pueden llamar, de forma segura. Cauril se expone como un servidor MCP: el agente descubre herramientas tipadas para leer y operar pagos. El dinero nunca pasa por Cauril y los datos de tarjeta tampoco (PCI SAQ-A).

Tu API de pagos ya es lo que un agente necesita: es máquina-llamable, idempotente (reintentar nunca cobra dos veces) y devuelve estados y webhooks normalizados. El paquete @cauril/mcp es solo el punto de entrada: expone esa misma API como herramientas MCP, hosteadas en api.cauril.com/mcp (conectás en un click) o corriendo local por stdio. No cambia nada del producto.

Cauril no custodia ni mueve fondos: el dinero va directo a tus cuentas con los PSPs. El servidor MCP no agrega un wallet ni un saldo del agente: expone la misma API normalizada, con candados.

Conectá en un click (hosteado)
No hace falta instalar ni correr nada: Cauril hostea el server en api.cauril.com/mcp. En el dashboard, al crear una API key, tocás "Conectar con un agente (MCP)" y se copia esta config lista, la pegás en tu cliente (Claude Desktop, Cursor, …):
mcp config (hosteado)
```
{
  "mcpServers": {
    "cauril": {
      "command": "npx",
      "args": ["-y", "mcp-remote",
        "https://api.cauril.com/mcp",
        "--header", "Authorization: Bearer sk_test_..."]
    }
  }
}
```
El agente se autentica con tu propia API key, así que solo puede hacer lo que esa key permite. Los clientes con soporte remoto nativo pueden usar "url" + headers en vez del shim mcp-remote. Listo: ya puede consultar pagos, clientes y analytics, y (si no lo restringís) crear pagos, reembolsos y sesiones de checkout.
O corrélo local (npx)
Si preferís correr el server vos (sin pasar por el endpoint hosteado), instalá el paquete @cauril/mcp. El cliente lo levanta con npx y la key va por variable de entorno:
mcp config (local)
```
{
  "mcpServers": {
    "cauril": {
      "command": "npx",
      "args": ["-y", "@cauril/mcp"],
      "env": { "CAURIL_API_KEY": "sk_test_..." }
    }
  }
}
```
Empezá en modo seguro (solo lectura)
Para dar acceso de solo lectura, agregá el header X-Cauril-MCP-Readonly: true (hosteado) o la env CAURIL_MCP_READONLY=true (local): las herramientas que mueven dinero ni siquiera se registran. Ideal para darle a un agente acceso a tus datos sin riesgo.
JSON
```
// hosteado: agregá un --header extra
"--header", "X-Cauril-MCP-Readonly: true"

// local: por env
"env": { "CAURIL_API_KEY": "sk_test_...", "CAURIL_MCP_READONLY": "true" }
```
Para cobrar, dejá que el humano ponga la tarjeta
La vía recomendada para que un agente cobre es create_checkout_session: devuelve un client_secret que tu página de checkout usa para montar el drop-in de Cauril, donde el comprador ingresa la tarjeta. Así ningún dato de tarjeta toca al agente ni a Cauril, y no se mueve dinero hasta que el comprador completa.
TEXT
```
agente → create_checkout_session({ amount: 5000, currency: "USD", success_url, cancel_url })
       → { id: "cs_…", client_secret: "cs_…_secret_…" }   // tu checkout monta el drop-in con este client_secret
```
¿Ya tenés un token del PSP (pm_…)? Entonces create_payment cobra directo. 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.

En modo local, el server se niega a arrancar con una key sk_live_ salvo que setees CAURIL_MCP_ALLOW_LIVE=true, así un agente no mueve plata real por accidente mientras desarrollás. El endpoint hosteado sí acepta tu key live (conectar tu propia key en producción es justamente el caso de uso). En cualquier caso, ninguna herramienta acepta un número de tarjeta crudo: eso es siempre del lado del PSP.

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.

Por qué es seguro

Solo lectura por defecto opcional: CAURIL_MCP_READONLY esconde todo lo que muta.
Candado de producción: las keys sk_live_ requieren opt-in explícito.
Idempotencia: un agente que reintenta no cobra dos veces.
SAQ-A: los datos de tarjeta van directo al PSP, vía checkout hospedado; nunca al agente.
Annotations MCP: cobro y reembolso se marcan como destructivos, así tu cliente puede pedir confirmación.

Conectá en un click (hosteado)

O corrélo local (npx)

Empezá en modo seguro (solo lectura)

Para cobrar, dejá que el humano ponga la tarjeta

Herramientas

Por qué es seguro