X402 MCP Proxy

x402 MCP代理

本地MCP（模型上下文协议）代理，连接到远程MCP服务器和 自动处理 x402 支付当远程MCP工具触发HTTP 402响应时，代理在链上签署USDC支付并重试——透明，客户端不需要更改。

运作原理

┌─────────────┐      stdio       ┌──────────────┐    HTTP + x402     ┌──────────────┐
│  AI Client   │ ◄──────────────► │  x402 Proxy  │ ◄────────────────► │ Remote MCP A │
│ (Claude, etc)│                  │  (this repo)  │                   ├──────────────┤
└─────────────┘                  │              │ ◄────────────────► │ Remote MCP B │
                                  └──────────────┘                   └──────────────┘

1. 代理连接到一个或多个远程MCP服务器（通过Streamable HTTP或SSE）。
2. 它发现他们的工具，并通过stdio将其重新暴露给AI客户端，前缀为服务器名称（例如。 cmc_get_quotes).
3. 当工具调用返回HTTP 402时，代理会拦截它，并对EIP-3009进行签名 transferWithAuthorization （USDC基于Base），并自动重试。

快速开始

1.安装

git clone https://github.com/coinmarketcap-official/x402-mcp-proxy.git
cd x402-mcp-proxy
pnpm install

2.配置远程MCP

创建 x402-mcps.json 在项目根目录中（请参见 x402-mcps.example.json):

{
  "x402mcpServers": [
    {
      "url": "https://pro.coinmarketcap.com/x402/mcp",
      "prefix": "cmc"
    },
    {
      "url": "https://other-mcp.example.com/mcp",
      "prefix": "other",
      "headers": {
        "Authorization": "Bearer your_token"
      }
    }
  ]
}

或者将其作为环境变量传递（前缀、url对）：

export X402_REMOTE_MCPS="cmc,https://pro.coinmarketcap.com/x402/mcp"

3.配置钱包

复制 .env.example 到 .env 并添加至少一个私钥：

cp .env.example .env

EVM_PRIVATE_KEY=0xYOUR_PRIVATE_KEY_HERE

EVM钱包需要在Base上使用USDC进行x402支付。还支持Solana（SVM）。

4.跑步

pnpm dev    # development (tsx)
pnpm build && pnpm start  # production

5.从AI客户端连接

克劳德桌面版 (claude_desktop_config.json):

{
  "mcpServers": {
    "x402": {
      "command": "npx",
      "args": ["tsx", "/path/to/x402-mcp-proxy/src/index.ts"],
      "env": {
        "EVM_PRIVATE_KEY": "0x...",
        "X402_REMOTE_MCPS": ["cmc", "https://pro.coinmarketcap.com/x402/mcp"]
      }
    }
  }
}

光标 (.cursor/mcp.json):

{
  "mcpServers": {
    "x402": {
      "command": "npx",
      "args": ["tsx", "/path/to/x402-mcp-proxy/src/index.ts"],
      "env": {
        "EVM_PRIVATE_KEY": "0x...",
        "X402_REMOTE_MCPS": ["cmc", "https://pro.coinmarketcap.com/x402/mcp"]
      }
    }
  }
}

您还可以指向配置文件以获取更高级的选项（自定义标头等）：

"X402_CONFIG": "/path/to/x402-mcps.json"

配置参考

远程MCP服务器

ENV 格式 --前缀/url对，不支持标头：

["cmc", "https://pro.coinmarketcap.com/x402/mcp"]

配置文件格式 --使用标头进行完全控制：

{
  "x402mcpServers": [
    {
      "prefix": "cmc",
      "url": "https://pro.coinmarketcap.com/x402/mcp"
    },
    {
      "prefix": "other",
      "url": "https://other.example.com/mcp",
      "headers": { "Authorization": "Bearer xxx" }
    }
  ]
}

钱包钥匙

x402支付处理至少需要一个密钥。

支付安全限制

代理在签名之前验证每个402支付请求。所有限制均可通过环境变量进行配置：

如果402响应请求超出这些限制的金额、网络或资产，则代理 拒绝付款并将原始402返回给客户 没有签署任何东西。当代理进程重新启动时，会话花费重置。

什么是x402？

x402 是Coinbase的一个开放协议，通过HTTP使用稳定币支付实现即时、按请求付费的API访问。当API返回HTTP 402时，客户端签署USDC转账授权，服务器的调解人只有在成功发送响应后才执行链上支付。

关键属性：

• 无需订阅 --使用USDC按请求付款
• 只为成功付出代价 --如果服务器未能返回数据，则签名的授权将过期而未使用，并且不会扣除任何付款
• 在基地工作 （EVM）和 索拉纳

项目结构

x402-mcp-proxy/
├── src/index.ts           # Proxy entry point
├── x402-mcps.example.json # Example remote MCP config
├── .env.example           # Example environment variables
├── package.json
├── tsconfig.json
└── LICENSE                # MIT

安全考虑

信任模型

此代理旨在运行 本地在您自己的机器上 作为基于stdio的MCP服务器。AI客户端（Claude、Cursor等）通过stdin/stdout与其通信——没有网络侦听器。因此，客户端和代理之间的身份验证由操作系统级进程隔离处理。

如果在 共享或多用户环境 （例如，多个用户访问的服务器），您应该在其前面添加一个身份验证层。默认的stdio传输不是为该用例设计的。

私钥存储

私钥从环境变量（通常为 .env 文件）。对于个人/开发用途，这是可以接受的，但对于生产或高价值钱包，请考虑：

• 操作系统钥匙链 集成（macOS钥匙链、Linux秘密服务）
• 硬件钱包 或 云KMS （AWS知识管理系统、GCP云知识管理系统）
• 加密的env文件 带有密码

永不承诺 .env 包含版本控制真正私钥的文件。

内置保护

默认情况下，代理附带了启用的几个安全检查：

• 每次请求的金额上限 --拒绝402个请求超过配置限制的响应
• 会议支出上限 --一旦累计支出达到阈值，就停止签名
• 网络和资产分配列表 --仅对明确允许的链和代币付款
• HTTPS强制 --如果任何远程MCP URL使用不安全的协议（非本地主机HTTP），则在启动时发出警告
• 经过净化的错误输出 --内部错误详细信息不会泄露给客户端
• 结构化支付审计日志 --每个签名的付款都会记录到stderr中，其中包含金额、网络、资产、收件人和目标URL

许可证

麻省理工学院