使用说明
代理mcp支付
MCP服务器的支付网关——用一个包装器将您的工具货币化
包裹任何 模型上下文协议 具有支付执行功能的服务器。特工们正常调用你的工具；网关拦截、发出支付质询、验证证明，然后执行。一个功能。无协议锁定。
安装
npm install agentic-mcp-pay
需要Node.js 18+。
快速启动
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { withPayments } from "agentic-mcp-pay";
const server = new McpServer({ name: "my-tools", version: "1.0.0" });
server.tool("analyze-data", {}, async (args) => {
return { content: [{ type: "text", text: "analysis result" }] };
});
const { server: paidServer, cleanup, dashboardUrl } = withPayments(server, {
pricing: {
"analyze-data": { amount: 0.50, currency: "usd" },
},
payTo: "0xYourWalletAddress",
protocols: ["x402"],
dashboard: { port: 3100 },
});
// Connect to transport as normal
// paidServer.connect(transport);
支持的协议
| 协议 | 描述 |
|---|---|
| x402 | 通过Coinbase服务商进行稳定币小额支付（USDC on Base） |
| 大规模并行处理 | 机器支付协议（Stripe/Tempo） |
| 条纹 | 通过Stripe PaymentIntents进行传统卡支付 |
| 嘲笑 | 用于测试的内存存根——始终验证 |
运作原理
Agent calls tool
│
▼
Gateway checks pricing table
│
├─ No price set ──────────────────► Execute immediately (passthrough)
│
├─ No _payment arg ───────────────► Return PAYMENT_REQUIRED + challenge
│
└─ _payment arg present
│
▼
Verify with protocol adapter
│
├─ Invalid / expired ─────► Return PAYMENT_INVALID / PAYMENT_EXPIRED
├─ Replay detected ───────► Return PAYMENT_REPLAY
├─ Underpaid ─────────────► Return PAYMENT_UNDERPAID
│
└─ Verified ──────────────► Execute tool, return result + receipt
- 特工在没有电话的情况下呼叫你的工具
_payment争论。 - Gateway返回a
PAYMENT_REQUIRED签名挑战（随机数、金额、payTo地址、到期日）出错。 - 代理通过API提交链上支付，并使用重试工具调用
_payment设置为证据。 - 网关根据协议适配器验证证明，检查重放保护，然后执行。
- 返回的结果为
_receipt块附加到内容数组。
这 _payment 论点被剥夺了 args 在调用处理程序之前，您的工具代码会看到干净的参数。
仪表盘
当 dashboard.port 设置后，本地仪表板将从以下位置开始 http://127.0.0.1:<port>/?token=<bearer>。URL（带令牌）返回为 dashboardUrl.
仪表板显示：
- 总收益和交易计数
- 每工具收入明细
- 最近的交易日志，包括状态、金额和协议
访问需要查询字符串中的承载令牌。令牌在每次进程启动时都是新生成的。
配置
所有选项 McpPayConfig:
| 字段 | 类型 | 必填 | 默认 | 描述 |
|---|---|---|---|---|
pricing |
Record<string, ToolPricing> |
是 | -- | 工具名称映射→ { amount, currency }。此地图中没有的工具可以免费通过。 |
payTo |
string |
是 | -- | 支付的目标地址（以太坊地址或Stripe帐户ID，具体取决于协议）。 |
protocols |
string[] |
是 | -- | 要启用的协议的有序列表： "x402", "mpp", "stripe", "mock". |
dashboard |
{ port: number } |
否 | 已禁用 | 启动上的本地仪表板 127.0.0.1:<port>. |
dbPath |
string |
没有 | ":memory:" |
SQLite路径用于挑战和事务存储。使用文件路径在重新启动时保持持久性。 |
challengeTtlMs |
number |
没有 | 300000 |
付款质询的有效期（毫秒）。默认值：5分钟。 |
facilitatorUrl |
string |
没有 | https://x402.org/facilitator |
覆盖x402主持人端点。 |
mppApiUrl |
string |
没有 | https://mpp.dev/api/verify |
覆盖MPP验证端点。 |
stripeSecretKey |
string |
没有 | MCP_PAY_STRIPE_SECRET env |
条纹密钥。如果未在config中设置，则返回到环境变量。 |
ToolPricing:
| 字段 | 类型 | 描述 |
|---|---|---|
amount |
number |
主要货币单位价格（例如。 0.50 =50美分美元）。 |
currency |
string |
ISO 4217货币代码（例如。 "usd"). |
安全
执行前验证。 在支付凭证通过协议适配器的验证之前，网关永远不会调用您的工具处理程序。无效、过期或重播的证明会立即返回错误。
没有私钥。 agentic-mcp-pay 没有签名密钥。付款是代理人的责任；网关仅验证证明。
重播保护。 每个经过验证的交易哈希都存储在SQLite中。具有相同证明的第二次尝试返回 PAYMENT_REPLAY.
非有效期+有效期。 每个挑战都包括一个加密随机数和一个 expiresAt 时间戳。网关拒绝针对过期挑战的证明。过期的挑战每60秒从存储中清除一次。
断路器。 没有入口的工具 pricing 它们是无条件通过的，永远不会被封锁。这是有意为之：免费工具保持免费，无需任何配置更改。
仪表板仅支持本地主机。 仪表板绑定到 127.0.0.1 并且需要承载令牌。它从不暴露在 0.0.0.0.
许可证
麻省理工学院
另见
- 代理mcp付费客户端 --买家SDK：透明自动支付、预算控制、多协议
- 代理mcp支付演示 --支付循环的完整端到端演示
- 教程：在5分钟内将MCP工具货币化
