@cauril/mcp

A Model Context Protocol server that lets AI agents call the Cauril payments API as tools — safely. It's the same API you already use (it wraps the official @cauril/node SDK); nothing about the product changes.

Money never passes through Cauril, and card data never passes through this server (PCI SAQ-A): to collect a payment, an agent creates a checkout session and hands the buyer the returned URL.

Install / run

The server speaks stdio, so most MCP clients run it via npx. Add it to your client config:

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

That's it — the agent can now read payments, customers and analytics, and (unless you lock it down) create payments, refunds and checkout sessions.

Configuration

| Variable | Required | Description | | --- | --- | --- | | CAURIL_API_KEY | yes | Your Cauril secret key (sk_test_… or sk_live_…). Never logged. | | CAURIL_MCP_READONLY | no | true → register only read-only tools. Hand the agent a safe posture. | | CAURIL_MCP_ALLOW_LIVE | no | Required to start with a sk_live_ key. Off by default so an agent can't move real money by accident. | | CAURIL_BASE_URL | no | Override the API base URL (default https://api.cauril.com). |

Safety model

Letting an agent near money is the risk, so the defaults are conservative:

• Read-only switch. CAURIL_MCP_READONLY=true registers only the read tools — the mutating ones simply don't exist on the wire.
• Live-key guard. A sk_live_ key is refused unless you explicitly set CAURIL_MCP_ALLOW_LIVE=true. Use sk_test_ while building.
• Idempotency. Every money-moving tool takes an idempotency_key. Reuse the same key on a retry and the operation runs at most once — an agent that retries can't double-charge.
• Integer amounts. Amounts are integers in the currency's minor unit (5000 = $50.00). Decimals are rejected with a message that tells the agent how to fix it.
• Tool annotations. Read tools are marked read-only; create_payment/refund_payment are marked destructive — so MCP clients can prompt for confirmation before the dangerous ones.
• SAQ-A. No tool accepts a raw card number. create_payment requires a PSP-side token; to collect a new card, use create_checkout_session and let the buyer enter it in the hosted flow.

Tools

Read-only (always available): get_payment, list_payments, get_refund, get_customer, list_customers, get_checkout_session, analytics_summary, list_events.

Mutating (omitted when CAURIL_MCP_READONLY=true): create_checkout_session, create_payment, refund_payment, create_customer.

The recommended way for an agent to charge

Use create_checkout_session. It returns a client_secret that your checkout page uses to mount the embedded Cauril drop-in, where the buyer enters their card. No card data ever touches the agent or Cauril, and no money moves until the buyer completes it:

agent → create_checkout_session({ amount: 5000, currency: "USD", success_url, cancel_url })
      → { id: "cs_…", client_secret: "cs_…_secret_…" }   // your checkout mounts the drop-in with this client_secret

Programmatic use

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

const server = createServerFromEnv(); // reads CAURIL_API_KEY, CAURIL_MCP_READONLY, …
await server.connect(new StdioServerTransport());

License

MIT