Examples

Payments API to MCP

Payments APIs need the tightest MCP boundary. Read tools are useful for support and finance agents, but money-moving tools must be narrow, audited, and often require explicit approval.

Updated Jun 25, 20268 min read

Implementation

Path to ship.

Generate read tools for customers, subscriptions, invoices, charges, payment status, and disputes.

Keep refunds, credits, cancellations, and payment method changes behind private auth and approval.

Add amount limits, currency checks, idempotency keys, and trace ids to every write-capable tool.

Test missing credentials, invalid amount, duplicate idempotency key, and successful read calls.

Guide

Recommended tool surface

Start with payment status reads: find customer, list invoices, inspect subscription state, and retrieve a charge. These tools help agents answer billing questions without touching funds.

For writes, expose specific actions with strict limits. A refund tool should require charge id, amount, reason, idempotency key, and policy evidence.

payments_get_customer_billing_state

Returns customer, subscription, invoice, and payment status in one compact support view.

Generated input schema

{
  "type": "object",
  "properties": {
    "customer_id": { "type": "string" },
    "email": { "type": "string" }
  },
  "oneOf": [
    { "required": ["customer_id"] },
    { "required": ["email"] }
  ]
}

Example tools/call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "payments_get_customer_billing_state",
    "arguments": {
      "email": "buyer@example.com"
    }
  }
}

payments_create_limited_refund

Creates a bounded refund with amount, reason, idempotency key, and audit metadata.

Generated input schema

{
  "type": "object",
  "properties": {
    "charge_id": { "type": "string" },
    "amount_cents": { "type": "integer", "minimum": 1, "maximum": 50000 },
    "currency": { "type": "string", "enum": ["usd", "eur", "gbp"] },
    "reason": { "type": "string", "enum": ["duplicate", "fraudulent", "requested_by_customer"] },
    "idempotency_key": { "type": "string" }
  },
  "required": ["charge_id", "amount_cents", "currency", "reason", "idempotency_key"]
}

Example tools/call

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "payments_create_limited_refund",
    "arguments": {
      "charge_id": "ch_123",
      "amount_cents": 2500,
      "currency": "usd",
      "reason": "requested_by_customer",
      "idempotency_key": "refund-ch_123-2026-06-25"
    }
  }
}

Guide

Production guardrails

Block broad create, update, and delete routes unless they are wrapped in a policy-specific tool. The agent should never improvise payment mutations from raw endpoint docs.

Return exact denial reasons for blocked money movement. The result should say whether a provider call was attempted, which policy blocked it, and which trace id connects the denial to logs.

FAQ

Common questions.

Can an MCP agent issue refunds?

Yes, but only through a bounded private tool with amount limits, idempotency, audit logs, and usually a human approval policy.

What payment tools should stay read-only?

Customer lookup, invoice status, subscription state, dispute detail, and charge retrieval are good read-only tools.