a2a-x402-mcp-services

面向生产的 x402 v2 收费 MCP 工具，用于真实的代理到代理（A2A）商业交易。

• 真实的链上结算（无模拟，无模拟支付）

• 完全符合当前 x402 v2 规范（CAIP-2 网络、PAYMENT-REQUIRED / PAYMENT-SIGNATURE / PAYMENT-RESPONSE 请求头、x402Version: 2、精确支付方案）

• 官方 @x402/mcp + @x402/core + @x402/evm 包

• Bazaar 就绪（工具可通过实现了 Bazaar 扩展的协调服务商被发现）

• 针对现有的生态缺口构建：代理实际会反复购买的操作型工具

当前付费工具

所有工具都使用精确的支付方案，并通过真实的协调服务商完成结算。

Related MCP server: Agent Commerce Suite

x402 v2 合规清单

• x402Version: 2

• CAIP-2 网络标识符（默认 eip155:84532 Base Sepolia，主网 eip155:8453）

• 官方请求头（PAYMENT-REQUIRED、PAYMENT-SIGNATURE、PAYMENT-RESPONSE）

• 通过 @x402/evm/exact 实现精确的支付方案

• 基于协调服务商的验证和结算（绝不在进程内自行结算）

• 为 MCP 工具发现提供 Bazaar 扩展元数据

• 由环境变量驱动的 payTo 地址（不硬编码生产钱包）

快速开始（测试网）

git clone https://github.com/Disseveru/a2a-x402-mcp-services.git
cd a2a-x402-mcp-services
npm install

# Required: receiving wallet (Base Sepolia)
export X402_PAY_TO_EVM=0xYourTestnetAddress

# Optional overrides
# export X402_NETWORK=eip155:84532
# export X402_FACILITATOR_URL=https://x402.org/facilitator
# export PORT=4022

npm run dev

健康检查（免费）：

curl http://localhost:4022/health

工具目录（免费）：

curl http://localhost:4022/tools

MCP 端点（付费）：

POST http://localhost:4022/mcp

使用任意支持 x402 v2 的 MCP 客户端（@x402/mcp 客户端辅助函数、CDP 管理的钱包等）。首次调用付费工具时会收到合法的 402 响应；客户端会签名并通过 PAYMENT-SIGNATURE 重试；协调服务商完成结算；然后返回工具结果。

迁移到主网

1. 设置一个主网收款地址：

   export X402_PAY_TO_EVM=0xYourMainnetAddress

2. 切换网络：

   export X402_NETWORK=eip155:8453

3. 使用生产协调服务商（示例 – CDP）：

   export X402_FACILITATOR_URL=https://api.cdp.coinbase.com/platform/v2/x402

   （如果所选协调服务商需要 CDP 凭据，请提供。）

4. 启动服务器。真实 USDC 将开始流动。

绝不要使用持有多余自身可承受损失资金的热部署运行主网。

架构

src/
  config.ts          – env-driven CAIP-2 + facilitator + payTo
  server.ts          – McpServer + official createPaymentWrapper (@x402/mcp)
  tools/
    definitions.ts   – paid tool implementations (real logic)
  index.ts           – Express host + Streamable HTTP MCP transport

设计原则

1. 无模拟 – 每条付费路径最终都会调用真实的协调服务商进行结算。

2. 仅 v2 – 不兼容旧的 X-PAYMENT 头部或 v1 网络字符串。

3. 操作必要性 – 工具可解决代理反复购买操作过程中遇到的真实问题（风险、规范化、协调服务商选择）。

4. 可发现性 – 带有 Bazaar 元数据，因此代理无需硬编码 URL 就能发现这些工具。

5. 运营商安全 – 收款地址和网络完全通过环境变量指定。

许可证

MIT