高级7 分钟阅读

PolyPay MCP 接入

通过 MCP 让 AI 客户端安全查询和操作商户订单、Webhook、x402 资源和接入文档。

连接端点

MCP 使用 Streamable HTTP，端点为 `/mcp`。使用商户 API Key 通过 `Authorization: Bearer <api_key>` 鉴权，也兼容 `X-API-Key` 请求头。

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" }
    }
  }'

权限范围

`mcp:read`：读取商户资料、订单、Webhook、x402 和文档。
`mcp:orders:write`：创建或取消订单。
`mcp:webhooks:write`：保存 Webhook 配置或重发投递。
`mcp:x402:write`：创建、启停或删除 x402 资源。
`mcp:admin`：管理员级 MCP 权限，谨慎启用。

可用工具

第一版包含 `merchant.get_profile`、`orders.list`、`orders.create`、`webhooks.save_config`、`x402.resources.save`、`docs.search` 等工具。后台可以按 API Key 限制允许工具。

写操作安全

所有写工具都必须传入 `idempotency_key`，同一个 key 重试会返回首次成功结果；如果同一个 key 携带不同参数，会被拒绝。

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"
      }
    }
  }'

审计与限额

每次 MCP 工具调用都会记录工具名、结果、摘要、IP 和 User-Agent。可在商户后台设置每日调用限额、每日写操作限额和 IP 白名单。