x402ai-mcp

x402ai-mcp

本地 MCP 服务，可让 AI 客户端（Claude Desktop、Claude Code、Cursor 等）调用按次付费的 x402ai 端点，通过 x402 protocol 在 Base 上以 USDC 按次付款，并为任意 x402 端点提供免费的检查工具。

它通过 stdio 在你的机器上运行。你向它提供买家密钥；它会通过签署 USDC 授权来响应每个 HTTP 402 付款质询，并返回结果。它不会为你托管，也不需要账户。

工具

工具	费用	功能
embed	$0.01	768 维文本嵌入（nomic-embed-text）
summarize	$0.02	输入文本摘要（小型本地 LLM）
ask	$0.04	简短回答，2-3 句话；无法访问网络、没有记忆，也可能出错
health	免费	x402ai 服务状态，以及本次会话的支出和剩余额度
inspect	免费	接收一个 URL：解码其 402 质询，运行 Coinbase 的 x402 验证器并查询 Bazaar 商家

付费工具接受一个最长 3,000 个字符的 input 字符串。health 和 inspect 无需密钥。

开始之前：使用专用钱包

此服务会持有一个能够支出资金的私钥。请使用一个仅用于此用途的新钱包，最多存入几美元的 Base 网络 USDC。付款方无需支付 Gas 费（EIP-3009），因此钱包只需要 USDC，不需要 ETH。 切勿使用持有你无法承受损失资产的钱包。钱包余额就是你的实际支出上限。

可以信任这个软件包吗？

此服务要求提供一个可用于消费的密钥，而且已有窃取密钥的假冒“x402 MCP”软件包被举报。 不要只相信这份 README 中的说法：以下声明都可以核查。

• 软件包绝不会发送或记录你的密钥。 它只会从 X402AI_BUYER_PRIVATE_KEY 中读取一次，并且仅用于在本地签署付款授权；密钥也会从错误消息中清除。服务运行期间，密钥会保留在此进程的环境和内存中，因此任何能够读取这些内容的对象（此进程中的其他代码、以你的用户身份运行的其他程序、客户端配置文件）都可以读取密钥。在进程内部清除该变量也不会改变这一点，因为 Linux 会通过 /proc 保留进程启动时的环境，并允许读取。
• 它联系的所有主机。 不会跟随任何请求的重定向；遇到重定向时，请求会被拒绝，调用也会失败。
  • https://api.x402ai.dev：付费工具和 health。签名后的授权只会发送到此处，且仅用于调用工具自身的路由和价格，并会在 300 秒内过期。
  • https://api.cdp.coinbase.com：仅在运行 inspect 时使用（Coinbase 的验证器和商家查询）。
  • 你传递给 inspect 的 URL：一次未付费请求（POST 请求使用固定请求正文）。不会签署任何内容。
• 没有遥测、分析或更新检查。
• 体积小且易于阅读。 src/ 中有五个源文件（约 600 行），使用 tsc 构建到 dist/。发布的软件包仅包含 dist/、此 README、LICENSE 和 package.json。
• 依赖项版本已固定。 直接依赖项均固定为精确版本。安装时，npm 会在依赖项声明的范围内重新解析它们的依赖项，因此这些依赖项并未冻结；仓库的 package-lock.json 记录了经过测试的精确依赖项集合。没有依赖项会运行安装脚本。所有依赖项都通过了 npm 注册表签名验证（npm audit signatures）。x402 客户端为 @x402/fetch 2.28.0，代码中设置了单笔付款上限。
• 消费防护机制可以防止诚实的代码超额消费；但无法抵御恶意软件包。 因此，上述内容都可以核查。

核查方法： 将已发布的文件与源代码进行比较（运行 npm pack x402ai-mcp@<version> 可下载准确的软件包压缩文件以供检查），确认软件包名称恰为 x402ai-mcp，并阅读 src/。

不要在包含已注资密钥的同一个客户端中运行未经审查的 MCP 服务。 以你的用户身份运行的任何其他程序（包括另一个 MCP 服务）通常都可以读取此进程的环境和客户端配置文件，其中以明文形式保存着密钥。

安装

需要 Node.js 20 或更高版本。将它添加到 MCP 客户端的配置中，例如：

{
  "mcpServers": {
    "x402ai": {
      "command": "npx",
      "args": ["-y", "x402ai-mcp"],
      "env": {
        "X402AI_BUYER_PRIVATE_KEY": "0x...",
        "X402AI_MAX_SESSION_USD": "0.25"
      }
    }
  }
}

请注意，大多数客户端会以纯文本形式存储此文件，因此密钥会以未加密的形式保存在磁盘上。这也是使用余额较低的专用钱包的另一个理由。

如需在不使用密钥且不产生任何消费的情况下试用，请设置 X402AI_DRY_RUN=1：付费工具会返回其将支付的价格报价，且绝不会签署任何内容。

配置

变量	默认值	含义
X402AI_BUYER_PRIVATE_KEY	无	买家密钥（十六进制）。仅付费工具需要。绝不会记录；会从错误消息中清除。
X402AI_MAX_SESSION_USD	0.25	此服务进程最多可消费的总额。值无效时，服务会在启动时停止。
X402AI_DRY_RUN	关闭	1 = 仅报价，绝不签署。无需密钥。

服务仅将日志写入 stderr（stdout 用于传输 MCP 协议）。启动时会显示是否已配置密钥、买家地址和会话消费上限。

支出保护措施

• 每笔付款：签名前，每个付费工具都会检查挑战是否针对 Base 主网、USDC、x402ai 的付款地址以及该工具自己的路由，且金额不超过该路由的价格。否则将拒绝付款。另设每笔付款最高 0.04 美元的限制，作为第二道检查。
• **授权有效期较短。**如果挑战要求授权有效期超过 300 秒，将在签名前拒绝，以免泄露的授权长时间可用。
• **每个会话：**签名前，每次付款尝试都会计入 X402AI_MAX_SESSION_USD 预留额度。达到上限后，付费工具将拒绝请求，直至服务重启。
• **会话上限按进程计算。**额度在内存中计数，服务重启后重置。即使使用同一个钱包，每个运行中的服务副本也各有独立上限。钱包余额是唯一的硬性限制：只存入你愿意损失的金额。
• **上限没有最高值。**例如，误输入 250 就意味着 250 美元。钱包余额始终是兜底限制。

注意事项

• **调用失败仍可能计入额度。**如果服务在付款签名后返回错误，预留额度仍会保留，因为已签名的授权仍可能完成结算。x402ai 的处理程序失败时不会向你收费，但会话上限会将此次尝试视为已支出。
• inspect 会将你提供的 URL 发送到 Coinbase 的 CDP（验证器和商家查询）。不要检查你想保密的 URL。
• inspect 会拒绝本地和私有地址（环回地址、私有地址段、链路本地地址、CGNAT、IPv6 ULA，以及封装在 IPv6 格式中的 IPv4 地址），并在 DNS 解析后进行检查。仅允许 https。 检查和请求之间仍可能发生 DNS 变更（DNS 重绑定）。
• **请将工具输出视为不可信数据。**回答和摘要由小型模型生成，可能有误；被检查端点的响应属于第三方内容。不要让这些内容充当对 Agent 的指令。
• 延迟：embed 通常不到一秒；summarize 和 ask 大约需要 5–15 秒（CPU 推理）。
• **Claude Code 可能会延迟加载工具架构。**Claude Code 默认延迟加载 MCP 工具架构，因此首次调用工具时可能会传入错误或空参数。启动 Claude Code 时设置 ENABLE_TOOL_SEARCH=false，即可预先加载这些架构。

许可证

MIT。与 Coinbase 或 x402 Foundation 无关联。