PolyPay MCP Integration

Let AI clients safely query and operate merchant orders, webhooks, x402 resources, and integration docs through MCP.

Endpoint

MCP uses Streamable HTTP at `/mcp`. Authenticate with `Authorization: Bearer <api_key>` or the compatible `X-API-Key` header.

curl https://api.polypay.ai/mcp \
  -H 'Authorization: Bearer your-api-key' \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "capabilities": {},
      "clientInfo": { "name": "merchant-agent", "version": "1.0.0" }
    }
  }'

Scopes

• `mcp:read`: read merchant profile, orders, webhooks, x402, and docs.
• `mcp:orders:write`: create or cancel orders.
• `mcp:webhooks:write`: save webhook settings or redeliver events.
• `mcp:x402:write`: create, enable, disable, or delete x402 resources.
• `mcp:admin`: administrator MCP access. Enable carefully.

Tools

The first version includes `merchant.get_profile`, `orders.list`, `orders.create`, `webhooks.save_config`, `x402.resources.save`, `docs.search`, and more. Allowed tools can be restricted per API Key.

Write safety

Every write tool requires `idempotency_key`. Retrying with the same key returns the first successful result; reusing the key with different arguments is rejected.

curl https://api.polypay.ai/mcp \
  -H 'Authorization: Bearer your-api-key' \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "orders.create",
      "arguments": {
        "idempotency_key": "order-20260701-001",
        "reason": "Create checkout from MCP client",
        "currency": "USDT",
        "network": "Tron",
        "amount": 10,
        "notify_url": "https://merchant.example.com/webhook"
      }
    }
  }'

Audit and limits

Every MCP tool call records tool name, result, summary, IP, and User-Agent. The dashboard supports daily call limits, daily write limits, and IP allowlists.