高階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 白名單。