让任意MCP客户端接入ixrail AgentPay:6个AgentPay支付工具配置完全指南
让任意MCP客户端接入ixrail AgentPay:6个AgentPay支付工具配置完全指南
ixrail AgentPay 是一款为 AI Agent 提供钱包、预算策略与 x402 支付通道的 VS Code 扩展,它内置 6 个 AgentPay 支付工具,并通过无依赖的 stdio MCP 服务器向任意 MCP 客户端开放。本文是一份完整配置指南,帮你快速完成 MCP 接入、工具配置与本地沙箱联调,全程无需离开编辑器。
1. 先了解:ixrail AgentPay 能做什么?
简单说,ixrail AgentPay 让本地 Agent 能"安全地花钱":
- 🔐 钱包:通过 VS Code
SecretStorage创建并保管,支持 Base Sepolia(沙箱)与 Base 主网 - 📊 支出策略:单笔、每日(UTC)、每月(UTC)三重限额 + 人工审批阈值 + 商户白/黑名单
- 🌐 本地代理:带 Bearer Token 认证的 localhost broker,供 HTTP 型 Agent 调用
- 🧾 签名收据:每笔结算生成规范化、防重放的签名回执
- 🔌 MCP 服务器:以 stdio JSON-RPC 方式暴露 6 个支付工具,任何 MCP 客户端都能接入
- 🧪 沙箱演示:内置 mock 商户(
http://127.0.0.1:4021/v1/weather,收费 0.05 USDC),零资金即可跑通"支付 → 收据"完整闭环
组件关系与数据流可参阅架构文档:docs/ARCHITECTURE.md。
2. 快速开始:启动 stdio MCP 服务器
MCP 服务器是一个独立 Node 进程,通过标准输入/输出与客户端通信,无需任何网络端口:
git clone https://gitcode.com/gh_mirrors/by/ixrail
cd ixrail
npm install
npm run build
npm run mcp-server
npm run mcp-server 实际执行的是 node out/mcp/server.js,脚本定义见 package.json。该服务器实现了完整的 MCP 生命周期(initialize、ping、工具发现、工具调用),并内置一个独立的 JSON 文件存储(默认 ~/.ixrail-agentpay/store.json)。
💡 如果已在 VS Code 中安装扩展,可直接用命令面板中的 Copy MCP Configuration,一键生成带正确 out/mcp/server.js 路径的客户端配置条目。
3. 6 个 AgentPay 支付工具逐个配置
以下 6 个工具同时暴露在 stdio MCP 与 HTTP broker 上,功能一致:
| 工具 | 作用 | 典型入参 |
|---|---|---|
pay_x402_endpoint |
核心支付工具:完成一次 x402 付费请求 | agentId、url、maxAmountUsd |
create_spending_policy |
创建/更新 Agent 的支出策略 | agentId、perTxCapUsd、dailyCapUsd、monthlyCapUsd、approvalThresholdUsd、allowlist、blocklist |
get_balance |
查询钱包余额(当前返回可用于 gas 的原生 ETH) | agentId |
request_payment |
发起一次受策略约束的支付请求 | agentId 等 |
get_receipt |
从签名收据台账中取回回执 | 收据相关参数 |
revoke_agent_access |
立即吊销某 Agent 的支付权限并释放预留额度 | agentId |
各工具的完整入参 schema 会在 MCP 客户端的"工具发现"阶段自动返回,接入后可直接查看。
3.1 pay_x402_endpoint:一次支付是怎么发生的
这是 6 个工具中的主角,其执行流程如下(源自 docs/ARCHITECTURE.md):
- Agent 调用
pay_x402_endpoint并传入目标 URL; - 先正常请求资源——若响应不是 HTTP 402,直接原样返回,不发生支付;
- 遇到 402 时,校验支付要求:正数金额、资产必须为
USDC、合法 EVM 收款地址、链为base-sepolia或base,并对照 Agent 策略与调用方maxAmountUsd上限; - 校验通过则预留额度、签名付款(模拟模式下生成合成结算,真实模式下广播 USDC 转账);
- 签名规范化收据后,携带
X-Payment-Proof与X-Ixrail-Receipt头重试原请求; - 支出计入每日/每月额度,释放预留。
3.2 create_spending_policy:给 Agent 定好"花钱规矩"
所有 x402 结算在签名前都会先过策略评估。关键控制项包括:单笔上限、UTC 日/月上限、审批阈值(达到该金额需开发者确认)、商户域名/收款地址白名单与黑名单(黑名单优先),以及 10 分钟支出预留(防止并发请求刷穿额度)。
在 MCP 客户端中这样调用(参数示例来自 README.md 的 HTTP 等价接口):
{
"agentId": "sandbox-demo",
"perTxCapUsd": 1,
"dailyCapUsd": 10,
"monthlyCapUsd": 100,
"approvalThresholdUsd": 0.5,
"allowlist": ["127.0.0.1"],
"blocklist": []
}
⚠️ 注意:独立运行的 MCP 进程没有 VS Code 审批弹窗,凡需要审批金额的结算默认被拒绝。若希望 Agent 无人值守支付,请有意地把 approvalThresholdUsd 设得足够高。
3.3 get_balance / get_receipt / revoke_agent_access
- get_balance:查询钱包可用于 gas 的原生 ETH 余额。注意:它目前不返回 USDC 代币余额,做真实转账前需另行确认 USDC 资金。
- get_receipt:取回某笔支付的签名收据。收据签名证明本地收据签名者生成了该载荷,可独立验证,但本身不代表链上最终确认。
- revoke_agent_access:一键熔断。吊销后立即拒绝该 Agent 的所有支付并清空其活跃预留,恢复访问时会重新应用已保存的策略。
4. MCP 客户端配置:mcpServers 示例
在你的 MCP 客户端配置中(如 Claude Desktop、Cursor 等)加入以下条目即可,完整示例见 README.md:
{
"mcpServers": {
"ixrail-agentpay": {
"command": "node",
"args": ["<仓库绝对路径>/out/mcp/server.js"],
"env": {
"IXRAIL_AGENTPAY_STORE": "<你的绝对路径>/agentpay-store.json"
}
}
}
}
要点:
command填node,args指向构建产物out/mcp/server.js;IXRAIL_AGENTPAY_STORE指定独立 JSON 存储位置,不填则默认使用~/.ixrail-agentpay/store.json;- MCP 走的是 stdio 上的换行分隔 JSON-RPC,不使用 HTTP Bearer Token——进程能否被启动本身就是信任边界,请限制谁能启动该进程并读取其存储文件。
5. 关键环境变量速查
| 变量 | 说明 | 默认值 |
|---|---|---|
IXRAIL_AGENTPAY_STORE |
独立 MCP/HTTP 进程使用的 JSON 存储 | ~/.ixrail-agentpay/store.json |
IXRAIL_BASE_SEPOLIA_RPC_URL |
Base Sepolia JSON-RPC 端点 | — |
IXRAIL_BASE_RPC_URL |
Base 主网 JSON-RPC 端点 | — |
IXRAIL_ALLOW_MAINNET_PAYMENTS |
设为 1 才允许 Base 主网 USDC 转账 |
未设置(禁用主网) |
IXRAIL_MOCK_MERCHANT_PORT |
沙箱 mock 商户端口 | 4021 |
另外,扩展设置中的 ixrail.simulateSettlement 默认为 true:模拟结算不会广播任何交易、不消耗资金,返回的是合成交易哈希,非常适合先在 MCP 客户端里联调全链路。关闭该设置并给钱包充值 Base Sepolia USDC + ETH 后,即可测试真实测试网转账。
6. 常见问题排查
MCP 客户端和 VS Code 里看到的钱包不一致
两者默认使用不同存储后端:VS Code 扩展用 SecretStorage,独立 MCP 进程用 JSON 文件。将 IXRAIL_AGENTPAY_STORE 指向与 MCP 进程相同的存储文件即可,VS Code 的 SecretStorage 不会自动共享到该文件。详见 README.md 的 Troubleshooting 部分。
支付被策略拒绝
依次检查:是否已被吊销、白/黑名单、单笔上限、当日/当月累计支出、活跃预留,以及调用方传入的 maxAmountUsd。
支付卡在"需要审批" 金额达到策略审批阈值。独立 stdio 进程无审批 UI,默认直接拒绝——调整策略后再试。
端口 4021/4022 被占用
分别用 IXRAIL_MOCK_MERCHANT_PORT 与 IXRAIL_HTTP_PORT 换端口,并同步更新支付 URL。
7. 安全建议:接入陌生端点前必看
- 🔒 把存储文件、broker token、钱包私钥都当密匙对待,不要提交或粘贴进日志;独立存储文件未加密,请靠操作系统权限保护;
- 🎯 x402 服务端自己控制返回的支付要求——白名单 + 低限额才是真正防线,结构校验挡不住恶意端点发起扣款请求;
- ⛓️ 本版本提交交易后不等待链上确认,处理真实资金前请自行核验交易状态;金额以 JavaScript 数字表示并保留 6 位小数,适合受控的开发场景而非高价值资金管理;
- 🛡️ 主网转账默认禁用,确需启用时先验证钱包、收款方与限额,再设置
IXRAIL_ALLOW_MAINNET_PAYMENTS=1。
🎉 至此,任意 MCP 客户端都可以通过 stdio 方式接入 ixrail AgentPay 的全部 6 个支付工具。先跑一遍沙箱演示熟悉"创建钱包 → 设策略 → 支付 → 验收据"的闭环,再切换到真实测试网,是风险最低的进阶路径。
📁 延伸阅读:README.md(完整行为说明)、docs/ARCHITECTURE.md(组件与信任边界)、CHANGELOG.md(版本演进)、构建配置 esbuild.js