内容
# x402 MCP 代理
一个本地的 MCP（模型上下文协议）代理，连接到远程 MCP 服务器并**自动处理 [x402](https://docs.cdp.coinbase.com/x402/welcome) 支付**。当远程 MCP 工具触发 HTTP 402 响应时，代理会在链上签署 USDC 支付并重试 — 透明地，无需在客户端进行任何更改。
## 工作原理
```
┌─────────────┐ stdio ┌──────────────┐ HTTP + x402 ┌──────────────┐
│ AI 客户端 │ ◄──────────────► │ x402 代理 │ ◄────────────────► │ 远程 MCP A │
│ （Claude等）│ │ （此仓库） │ ├──────────────┤
└─────────────┘ │ │ ◄────────────────► │ 远程 MCP B │
└──────────────┘ └──────────────┘
```
1. 代理连接到一个或多个远程 MCP 服务器（通过 Streamable HTTP 或 SSE）。
2. 它发现这些服务器的工具，并通过 stdio 将它们重新暴露给 AI 客户端，并以服务器名称为前缀（例如 `cmc_get_quotes`）。
3. 当工具调用返回 HTTP 402 时，代理会拦截它，签署 EIP-3009 `transferWithAuthorization`（Base 上的 USDC），并自动重试。
## 快速入门
### 1. 安装
```bash
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`）：
```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"
}
}
]
}
```
或作为环境变量传递（前缀，网址对）：
```bash
export X402_REMOTE_MCPS="cmc,https://pro.coinmarketcap.com/x402/mcp"
```
### 3. 配置钱包
复制 `.env.example` 到 `.env` 并添加至少一个私钥：
```bash
cp .env.example .env
```
```env
EVM_PRIVATE_KEY=0xYOUR_PRIVATE_KEY_HERE
```
EVM 钱包需要在 Base 上拥有 USDC 以进行 x402 支付。Solana（SVM）也受支持。
### 4. 运行
```bash
pnpm dev # 开发环境（tsx）
pnpm build && pnpm start # 生产环境
```
### 5. 从 AI 客户端连接
**Claude Desktop**（`claude_desktop_config.json`）：
```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**（`.cursor/mcp.json`）：
```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"]
}
}
}
}
```
您还可以指向配置文件以获取更多高级选项（自定义标头等）：
```json
"X402_CONFIG": "/path/to/x402-mcps.json"
```
## 配置参考
### 远程 MCP 服务器
| 来源 | 描述 |
|--------|------------|
| `X402_REMOTE_MCPS` 环境变量 | 平坦的配对列表：`["prefix","url",…]` 或 `"prefix,url,…"`（优先级最高） |
| `X402_CONFIG` 环境变量 | 自定义 JSON 配置文件的路径 |
| `x402-mcps.json` | 项目根目录下的默认配置文件 |
**环境变量格式** — 前缀/网址对，无标头支持：
```json
["cmc", "https://pro.coinmarketcap.com/x402/mcp"]
```
**配置文件格式** — 完全控制标头：
```json
{
"x402mcpServers": [
{
"prefix": "cmc",
"url": "https://pro.coinmarketcap.com/x402/mcp"
},
{
"prefix": "other",
"url": "https://other.example.com/mcp",
"headers": { "Authorization": "Bearer xxx" }
}
]
}
```
### 钱包密钥
| 环境变量 | 描述 |
|-------------|-------------|
| `EVM_PRIVATE_KEY` | EVM 私钥（0x-prefixed hex）。用于 Base 上的 USDC 支付。 |
| `SVM_PRIVATE_KEY` | Solana 私钥（base58-encoded）。用于 Solana 上的 USDC 支付。 |
x402 支付处理至少需要一个密钥。
### 支付安全限制
代理在签署之前验证每个 402 支付请求。所有限制都可以通过环境变量配置：
| 环境变量 | 默认值 | 描述 |
|-------------|---------|-------------|
| `X402_MAX_PAYMENT` | `100000`（0.10 USDC） | 每个请求的金额上限（以资产最小单位为单位） |
| `X402_MAX_SPEND_PER_SESSION` | `1000000`（1.00 USDC） | 每个代理会话的累计支出上限 |
| `X402_ALLOWED_NETWORKS` | `eip155:8453,solana:5eykt…` | CAIP-2 网络 ID 的逗号分隔允许列表 |
| `X402_ALLOWED_ASSETS` | Base USDC, Solana USDC | 资产合约地址的逗号分隔允许列表 |
如果 402 响应请求的金额、网络或资产超出这些限制，代理将**拒绝支付并将原始 402 返回给客户端**，而不会签署任何内容。会话支出在代理进程重启时重置。
## 什么是 x402？
[x402](https://docs.cdp.coinbase.com/x402/welcome) 是 Coinbase 的一个开放协议，它通过 HTTP 上的稳定币支付实现即时、按需请求的 API 访问。当 API 返回 HTTP 402 时，客户端签署 USDC 转移授权，服务器的促进者在成功交付响应后执行链上支付。
关键属性：
- **无需订阅** — 使用 USDC 按需支付
- **仅在成功时支付** — 如果服务器无法返回数据，则签名的授权将过期且不会被扣除
- **在 Base（EVM）和 Solana 上运行**
## 项目结构
```
x402-mcp-proxy/
├── src/index.ts # 代理入口点
├── x402-mcps.example.json # 示例远程 MCP 配置
├── .env.example # 示例环境变量
├── package.json
├── tsconfig.json
└── LICENSE # MIT
```
## 安全考虑
### 信任模型
此代理设计为在**您自己的本地机器上**作为基于 stdio 的 MCP 服务器运行。AI 客户端（Claude、Cursor 等）通过 stdin/stdout 与其通信 — 没有网络监听器。因此，客户端和代理之间的身份验证由 OS 级进程隔离处理。
如果您在**共享或多用户环境**（例如多个用户访问的服务器）中部署此代理，则应在代理前面添加身份验证层。默认的 stdio 传输不适用于这种情况。
### 私钥存储
私钥从环境变量（通常是 `.env` 文件）中加载。对于个人/开发使用，这是可以接受的，但对于生产或高价值钱包，请考虑：
- **OS 密钥链** 集成（macOS 密钥链，Linux 秘密服务）
- **硬件钱包** 或 **云 KMS** （AWS KMS，GCP Cloud KMS）
- **加密环境文件** 及口令短语
永远不要将包含真实私钥的 `.env` 文件提交到版本控制中。
### 内置保护
代理默认启用了多个安全检查：
- **每个请求的金额上限** — 拒绝请求超过配置限制的 402 响应
- **会话支出上限** — 累积支出达到阈值时停止签署
- **网络和资产允许列表** — 仅在明确允许的链和代币上支付
- **HTTPS 强制** — 如果任何远程 MCP URL 使用不安全的协议（非本地主机 HTTP），则在启动时发出警告
- **清理错误输出** — 内部错误详细信息不会泄露给客户端
- **结构化支付审计日志** — 每个签名的支付都会记录到 stderr，包含金额、网络、资产、收款人和目标 URL
## 许可证
[MIT](LICENSE)
