mcp-x402-accept

@cryptoapis-io/mcp-x402-accept

在你已运行的 MCP 服务前加上 x402 付费墙——按次向 AI Agent 收费，无需修改该服务的一行代码。

agent  →  mcp-x402-accept (your process)  →  your existing MCP server

对于 Agent 来说，此代理是 MCP 服务；对于你的服务来说，它是 MCP 客户端。它会镜像你的服务公开的所有工具；你设定价格的工具会加上付费墙，其余工具则免费直通。

适用场景（以及不适用场景）

你的情况	使用
你可以编辑自己的 MCP 服务（Node/TS）	x402-merchant-sdk/mcp——在处理程序周围加三行代码，不会影响数据流
你不能——例如服务由第三方提供、为闭源服务，或不是 Node 服务	此代理

如果你可以编辑自己的服务，就直接这么做。这种方式更简单，需要的组件也更少。此软件包是为无法采用这种方式的情况准备的。

为什么只能自托管

此进程由你运行。我们绝不代为运行，也不提供托管版本。

这是有意为之的产品决策，并非可切换的默认设置。代理位于 Agent 和你的服务之间，因此托管代理意味着 CryptoAPIs 将持有你上游服务的凭据，处于工具参数和结果的明文传输路径中，还要为你自己的收入承担服务可用性责任。对于产品本身就是这些调用所传输数据的商家来说，这种要求并不合理。自托管无需回答这个问题，就能消除顾虑。

从架构上看，这能保证：

• 代理无法读取工具参数和结果。它只读取工具名称（是否设定了价格？）和 _meta["x402/payment"]（是否已付款？）——仅此而已。它绝不会解析、记录、缓冲或缓存这些内容。
• 你的上游凭据是你自己进程中的环境变量。
• 唯一的出站调用是向 CryptoAPIs facilitator 发起，用于对付款本身执行 /verify 和 /settle。

安装

npm install -g @cryptoapis-io/mcp-x402-accept

配置

{
  "upstream": {
    "transport": "stdio",
    "command": "node",
    "args": ["/path/to/your-mcp-server.js"],
    "env": { "YOUR_UPSTREAM_TOKEN": "${YOUR_UPSTREAM_TOKEN}" }
  },

  "apiKey": "${CRYPTOAPIS_API_KEY}",
  "payTo":  "0xYourReceivingAddress",

  // Only these are charged for. Everything else your server exposes stays FREE.
  "pricedTools": {
    "premium_data": {
      "network": "eip155:8453",
      "asset":   "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "amount":  "10000"
    }
  }
}

${VAR} 会从环境中读取，因此配置文件本身不含密钥，可以安全地提交。

amount 的单位是最小单位——USDC 有 6 位小数，因此 "10000" 相当于 $0.01。这里最容易犯的错误就是差 10^6 倍。

使用 HTTP 上游而不是 stdio：

"upstream": {
  "transport": "http",
  "url": "https://your-server.example.com/mcp",
  "headers": { "Authorization": "Bearer ${YOUR_UPSTREAM_TOKEN}" }
}

如需为一个工具接受多种资产或网络，请传入数组——由 Agent 选择其中一种。只提供 GET https://ai.cryptoapis.io/x402/merchant/supported 列出的选项（公开，无需密钥）；其他选项即使被公布，也会在 /verify 时遭到拒绝。

运行

cryptoapis-mcp-x402-accept --config ./x402-accept.config.json

然后让 Agent 连接代理，而不是你的服务。在 Claude Code 中：

claude mcp add my-paid-tools -- cryptoapis-mcp-x402-accept --config /abs/path/to/config.json

所有内容都会在启动时验证——包括配置、上游连接，以及你设定价格的工具是否确实存在于上游。工具名称拼写错误会导致启动失败，而不是悄无声息地造成收入损失：否则你可能以为某个工具已加上付费墙，实际上它却一直免费提供服务。

Agent 看到的内容

步骤	结果
未付款便调用已设定价格的工具	isError: true，其中 PaymentRequired 同时包含在 structuredContent 和 content[0].text 中
Agent 付款	在本地签名，并在 _meta["x402/payment"] 中携带负载重试——原始 JSON，无 base64
已付款的调用	返回你工具的真实结果，并在 _meta["x402/payment-response"] 中附上收据
调用未设定价格的工具	免费转发，不作更改

**付款结算完成之前，绝不会调用你的服务。**代理先收费，再转发——不会先转发后收费。未付款的调用根本无法到达你的服务，因此无法让它免费完成工作。

已设定价格的工具会在说明中标注 [paid: x402]，让 Agent 在调用之前就知道费用。若 Agent 只能在被拒绝后才得知价格，就已经白白浪费了一次往返。

付款方式

Agent 可以使用 @cryptoapis-io/mcp-x402-pay 付款；也可以在代码中使用 @cryptoapis-io/x402-buyer-sdk/mcp。

备注

• 需要具备 X402_FACILITATOR 功能的 CryptoAPIs API 密钥。
• "settle": false 会执行验证，但不进行结算——在接线配置期间很有用，但仅供参考：买家证明了自己能够付款，而非已经付款。切勿将其用于正式环境。
• 在收取真实费用前，请先在 Base Sepolia（eip155:84532）上进行端到端测试。
• 实现了 x402 v2 MCP 传输协议 (规范)，并与商户 SDK 共用一套实现——规范修复会同时应用于两者。