API Reference

mcp2p exposes payment capabilities through the Model Context Protocol (MCP). This section documents the protocol basics, how mcp2p tools are structured, the request/response format, and authentication.

MCP protocol basics

MCP is an open protocol that enables AI assistants to call external tools in a structured, type-safe way. An MCP server exposes a list of tools, each with a name, description, and JSON Schema for its input parameters. The AI client discovers the tool list, decides when to invoke a tool based on the user's intent, and sends a tool call with structured arguments.

mcp2p implements an MCP server using @modelcontextprotocol/sdk and registers payment tools automatically based on the rails you configure. You do not need to interact with the MCP protocol directly — the SDK handles all protocol details.

Transport

The default transport is stdio. The AI client (e.g., Claude Desktop) spawns your server process and communicates over stdin / stdout using line-delimited JSON-RPC 2.0 messages. No HTTP server, no ports to open.

How mcp2p tools work

mcp2p registers one set of tools per enabled rail. Each rail provides three tools following a consistent naming pattern:

See MCP Tools for the full parameter schemas of every tool.

Request format

Tool calls are sent from the AI client to the MCP server as JSON-RPC 2.0 requests. You do not need to construct these manually — your MCP client handles this. For reference, a tool call looks like:

// JSON-RPC request from AI client to mcp2p server
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "spei_send_payment",
    "arguments": {
      "clabe": "014027000005555558",
      "amount": 50000,
      "concept": "Invoice #42",
      "recipientName": "Empresa Demo SA de CV",
      "verificationCode": "847291"  // optional — omit to trigger 2FA
    }
  }
}

Response format

All mcp2p tools return a structured response wrapped in the MCP CallToolResult envelope. The inner payload always follows the { data, error } shape:

Success response

// JSON-RPC response
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{"data":{"status":"success","trackingKey":"2024012614574900000012345678","amount":50000,"currency":"MXN","settledAt":"2024-01-26T14:57:52Z"},"error":null}"
      }
    ],
    "isError": false
  }
}

2FA required response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{"data":{"status":"2fa_required","message":"Verification code sent via SMS. Please provide the code to authorize the payment."},"error":null}"
      }
    ],
    "isError": false
  }
}

Error response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{"data":null,"error":{"code":"SPEI_INVALID_CLABE","message":"The provided CLABE failed checksum validation.","details":{"clabe":"014027000005555558"}}}"
      }
    ],
    "isError": true
  }
}

Authentication headers

The MCP server process itself does not expose HTTP endpoints, so there are no HTTP authentication headers for tool calls. Authentication is enforced through the license key at startup (Gate 2) and per-call (Gate 3).

If you are calling the mcp2p license server REST API directly (for validation or usage queries), authenticate using a Bearer token:

fetch("https://license.mcp2p.dev/api/v1/license/validate", {
  headers: {
    Authorization: `Bearer ${process.env.MCP2P_LICENSE_KEY}`,
    "Content-Type": "application/json",
  },
})

Tool discovery

MCP clients discover available tools by calling the tools/list method. mcp2p returns the full list of registered tools with their names, descriptions, and JSON Schema input definitions. The AI uses this schema to understand how to call each tool and what parameters to pass.

// Request
{ "jsonrpc": "2.0", "id": 0, "method": "tools/list" }

// Response (abbreviated)
{
  "result": {
    "tools": [
      {
        "name": "spei_send_payment",
        "description": "Send a SPEI interbank transfer to a CLABE account...",
        "inputSchema": {
          "type": "object",
          "properties": {
            "clabe": { "type": "string", "description": "18-digit CLABE..." },
            "amount": { "type": "number", "description": "Amount in centavos..." },
            ...
          },
          "required": ["clabe", "amount", "concept", "recipientName"]
        }
      }
    ]
  }
}

Sub-pages

• MCP Tools — Complete tool reference with full parameter tables, return types, and example request/response pairs for every tool across all rails.
• Error Codes — Categorized error code reference: license errors, validation errors, payment errors, rate limit errors, and 2FA errors with resolutions.