x402 Universal Payer

@three-ws/mcp-bridge

一个 MCP 服务，即可支付开放网络上任何采用 x402 付费的端点——面向 AI Agent 的通用 x402 付款方。

快速开始 · 安全 · 工具 · 环境 · three.ws

---

一个 Model Context Protocol 服务，可支付开放网络上任何采用 x402 付费的端点。让 Agent 访问一个会返回 402 Payment Required 的 URL；桥接程序会签名、付款、重试，并返回响应和结算凭证——支持 EVM 精确支付、EVM 批量结算和 Solana 精确支付，且均受严格的支出上限控制。它还会为在 Coinbase x402 Bazaar 上发现的每项服务预加载一个工具，让整个付费 API 经济体系都出现在工具列表中。

快速开始

Claude Code：

claude mcp add x402-bridge -e MCP_BRIDGE_SVM_PRIVATE_KEY=... -- npx -y @three-ws/mcp-bridge

也可以改用（或同时使用）-e MCP_BRIDGE_EVM_PRIVATE_KEY=0x...，以在 Base 和其他 EVM 链上付款。至少需要一个密钥。

Claude Desktop（claude_desktop_config.json）或 Cursor（~/.cursor/mcp.json）：

{
	"mcpServers": {
		"x402-bridge": {
			"command": "npx",
			"args": ["-y", "@three-ws/mcp-bridge"],
			"env": {
				"MCP_BRIDGE_EVM_PRIVATE_KEY": "0x…buyer key…",
				"MCP_BRIDGE_SVM_PRIVATE_KEY": "…base58 64-byte secret key…",
				"MCP_BRIDGE_MAX_PRICE_PER_CALL_ATOMIC": "100000",
				"MCP_BRIDGE_DISCOVER_LIMIT": "20"
			}
		}
	}
}

重启客户端，然后提出类似“在 Base 上支付 $0.01 获取天气报告”的请求——模型会选择匹配的 Bazaar 工具（或 call_paid_endpoint），桥接程序则通过 x402 自动付款。

安全与支出控制

此服务持有私钥，并会花费真实的 USDC。 配置前请阅读本节。

• 使用专用的低余额钱包。 MCP_BRIDGE_EVM_PRIVATE_KEY / MCP_BRIDGE_SVM_PRIVATE_KEY 绝不能是主钱包。只向其中存入你愿意让 Agent 花费的金额。
• 单次调用上限。 任何超过 MCP_BRIDGE_MAX_PRICE_PER_CALL_ATOMIC（默认值 100000 = $0.10 USDC）的付款，都会在签署负载前被拒绝，并返回包含网络、资产和上限信息的错误。
• 会话总额上限。 每个进程的累计支出上限由 MCP_BRIDGE_MAX_TOTAL_ATOMIC 控制（默认值 1000000 = $1.00 USDC）。这可以限制循环运行或遭到提示词注入的 Agent 所造成的损失：达到上限后，后续所有付款都会中止，直到重启进程。累计器会以原子方式预留额度，因此并发调用无法共同突破上限。
• 收款方允许列表。 设置 MCP_BRIDGE_ALLOWED_PAYTO（以逗号分隔的地址），拒绝向任何未明确设为可信的收款方付款。
• SSRF 防护。 每个出站的付费 URL——无论由模型提供还是来自 Bazaar 列表——都会经过同一个检查点，该检查点强制执行仅允许 https 的协议策略、解析主机名，并在任何解析出的地址属于私有、环回、链路本地（包括 169.254.169.254 云元数据地址）、CGNAT、ULA 或未指定地址时拒绝请求。字面 IP 主机将直接检查；永不跟随重定向（公共主机无法通过 3xx 将 bridge 引向内部基础设施）。只有显式启用开发选项 MCP_BRIDGE_ALLOW_HTTP=1 后才允许使用 http://。
• 主机允许列表。 设置 MCP_BRIDGE_ALLOWED_HOSTS（以逗号分隔的主机名）启用严格模式：只有列出的主机才能被付费访问。
• 存款上限。 批量结算通道的存款上限由 MCP_BRIDGE_MAX_DEPOSIT_ATOMIC 控制（默认值为 $5.00），无论服务请求的金额是多少。
• 如实标注。 每个付费工具都标注为 readOnlyHint: false、idempotentHint: false、openWorldHint: true，以便 MCP 主机应用最严格的确认策略。重试付费调用会产生新的费用。

提供的功能

启动时，bridge 会注册：

工具	功能
call_paid_endpoint	通用备用工具：访问任意 URL；若返回 402，则自动付款。返回响应及解析后的结算信息。
list_bazaar_tools	返回 Bazaar 发现的工具缓存列表（名称、资源、可接受的付款条款）。免费。
refresh_bazaar	重新查询 x402 Bazaar，并重新注册动态工具，无需重启。免费。
paid_<derived> …	每个发现的 Bazaar 资源对应一个工具（最多 MCP_BRIDGE_DISCOVER_LIMIT 个），并采用该端点的架构。

在发现阶段，所有价格都超过单次调用上限的工具会被过滤，因此模型看不到自己无力支付的工具。

工具注解

每个工具都带有 MCP ToolAnnotations，以便宿主应用采用适当的确认策略：

• call_paid_endpoint 和所有动态 paid_* 工具：readOnlyHint: false、destructiveHint: false、idempotentHint: false、openWorldHint: true。这些工具会实际花费 USDC——每次调用都会结算一笔付款（上限为 MCP_BRIDGE_MAX_PRICE_PER_CALL_ATOMIC），重试会产生新的费用。它们绝不会删除或覆盖调用方状态，因此不具有破坏性。
• list_bazaar_tools：readOnlyHint: true、idempotentHint: true、openWorldHint: false。仅读取进程内缓存；免费，不访问网络。
• refresh_bazaar：readOnlyHint: false、destructiveHint: false、idempotentHint: false、openWorldHint: true。免费（不付款），但它会根据实时 Bazaar 数据源更改已注册的工具集，因此重复调用可能得到不同结果。

纯对象形式的工具结果会同时以 JSON text 块和 structuredContent 返回，以兼容旧版本并支持类型化客户端。

付款方案

买方客户端上注册的付款路径：

• eip155:* → BatchSettlementEvmScheme（服务端公布该方案时优先使用；基于凭证，无需为每次调用支付 Gas）
• eip155:* → ExactEvmScheme（服务端公布 scheme: "exact" 时使用）
• solana:* 和 x402 v1 Solana 网络（solana、solana-devnet、solana-testnet）→ ExactSvmScheme / ExactSvmSchemeV1（由公布的费用支付方共同签名的 USDC SPL 转账），通过 registerExactSvmScheme() 一并注册。大多数开放的 x402 Bazaar 仍使用 v1 线格式；当卖方同时公布 v1 和 v2 时，客户端始终优先选择 v2。支出上限钩子会读取 amount（v2）或 maxAmountRequired（v1），因此两者的上限处理方式相同。

批量结算通道状态会持久化到 ~/.x402-mcp-bridge/channels/client/，因此客户端重启后，下次调用时不会再次存入资金。

环境

变量	必需	默认值	说明
MCP_BRIDGE_EVM_PRIVATE_KEY	EVM/SVM 中至少需要一个	—	带 0x 前缀的 32 字节十六进制值。用于在 Base、Arbitrum 等网络上支付 USDC。
MCP_BRIDGE_SVM_PRIVATE_KEY	EVM/SVM 中至少需要一个	—	base58 编码的 64 字节密钥（Phantom/solana-keygen 格式）或 64 个整数构成的 JSON 数组。
MCP_BRIDGE_MAX_PRICE_PER_CALL_ATOMIC	否	100000（= 6 位小数下的 0.10 USDC）	单次调用的支出上限。超过此值时，支付会中止并给出明确原因。
MCP_BRIDGE_MAX_TOTAL_ATOMIC	否	1000000（= 1.00 USDC）	会话累计支出上限。达到上限后会中止后续支付。
MCP_BRIDGE_ALLOWED_PAYTO	否	—（任意收款方）	以逗号分隔的收款方允许列表。设置后，不在列表中的 payTo 地址会被拒绝。
MCP_BRIDGE_ALLOWED_HOSTS	否	—（任意公共主机）	以逗号分隔的出站付费请求主机名允许列表。
MCP_BRIDGE_ALLOW_HTTP	否	0	设置为 1 以允许 http:// 目标。仅用于本地开发。
MCP_BRIDGE_DISCOVER_LIMIT	否	20	动态注册的 Bazaar 工具数量上限。设置为 0 可禁用发现功能。
MCP_BRIDGE_BAZAAR_URL	否	https://api.cdp.coinbase.com/platform/v2/x402/discovery/resources	可覆盖此值，指向可自托管或其他 Bazaar。
MCP_BRIDGE_BATCH_DEPOSIT_MULTIPLIER	否	5	打开批处理通道时一次性存入的请求金额倍数。
MCP_BRIDGE_MAX_DEPOSIT_ATOMIC	否	5000000（= 5.00 USDC）	每次打开通道或追加存款的存款金额硬性上限。
X402_MCP_BRIDGE_CHANNELS_DIR	否	~/.x402-mcp-bridge/channels	覆盖 FileClientChannelStorage 使用的目录。
RPC_URL_<chainId>	否	viem 默认公共 RPC	按链覆盖 RPC。示例：RPC_URL_8453=https://mainnet.base.org。

如果已设置 EVM_PRIVATE_KEY / SVM_PRIVATE_KEY，MCP_BRIDGE_* 密钥变量也会回退使用它们。

支出上限行为

支付前钩子会检查选定的 accepts 条目；如果金额超过单次调用上限、收款方不在允许列表中，或会话支出将超出上限，就会中止载荷创建。随后，工具结果会附带明确的错误消息，指出网络、资产以及触及的上限，方便模型判断是否需要请求你提高上限。

无需客户端进行检查

MCP_BRIDGE_SVM_PRIVATE_KEY=... npx -y @modelcontextprotocol/inspector npx -y @three-ws/mcp-bridge

检查器通过 stdio 连接，并列出静态工具（call_paid_endpoint、list_bazaar_tools、refresh_bazaar），以及为每个发现的 Bazaar 条目提供的一个动态工具。

编程方式使用

任何 Node 模块都可以通过同一个买方客户端使用 x402 端点：

import { buildBuyerAxios } from '@three-ws/mcp-bridge/src/x402-axios-client.js';

const { api } = await buildBuyerAxios();
const res = await api.get('https://api.example.com/some-paid-resource');

相同的支出上限、SSRF 防护和通道存储规则均适用。闲置的批处理通道可以通过 @x402 SDK 的 client.refund(resourceUrl, { amount }) 在带外退款。

测试

npm test           # hermetic: url-guard SSRF policy, spending-cap hook, tool naming, stdio boot
npm run test:smoke # live: boots against the real Bazaar and asserts the cap blocks a real paid call

隔离测试套件会在进程内生成临时密钥对；不会涉及任何真实密钥或资金。

许可证

版权所有。请参阅 LICENSE。