Agents SDK 提供的 paidTool 可以注册带有 x402 支付要求的工具。客户端按工具调用付费;同一服务器中可以同时包含免费和付费工具。
agents/x402 需要 @modelcontextprotocol/sdk,这是 agents 的可选对等依赖项。它不会在运行时加载该程序包,但其类型引用 MCP SDK v1。请在 package.json 中添加 Agents 版本所需的精确版本,例如 @modelcontextprotocol/[email protected]。
用 withX402 包装 McpServer,对要收费的工具使用 paidTool:
import { McpServer } from "@modelcontextprotocol/server";
import { createMcpHandler } from "agents/mcp/server";
import { withX402 } from "agents/x402";
import { z } from "zod";
const X402_CONFIG = {
network: "base",
recipient: "0xYourWalletAddress",
facilitator: { url: "https://x402.org/facilitator" }, // Payment facilitator URL
// To learn more about facilitators: https://docs.x402.org/core-concepts/facilitator
};
function createServer() {
const server = withX402(
new McpServer({ name: "PaidMCP", version: "1.0.0" }),
X402_CONFIG,
);
// Paid tool — $0.01 per call
server.paidTool(
"square",
"Squares a number",
0.01, // USD
{ number: z.number() },
{},
async ({ number }) => {
return { content: [{ type: "text", text: String(number ** 2) }] };
},
);
// Free tool
server.registerTool(
"echo",
{ description: "Echo a message", inputSchema: { message: z.string() } },
async ({ message }) => {
return { content: [{ type: "text", text: message }] };
},
);
return server;
}
const handler = createMcpHandler(createServer);
export default {
fetch(request, env, ctx) {
return handler(request, env, ctx);
},
};import { McpServer } from "@modelcontextprotocol/server";
import { createMcpHandler } from "agents/mcp/server";
import { withX402, type X402Config } from "agents/x402";
import { z } from "zod";
const X402_CONFIG: X402Config = {
network: "base",
recipient: "0xYourWalletAddress",
facilitator: { url: "https://x402.org/facilitator" }, // Payment facilitator URL
// To learn more about facilitators: https://docs.x402.org/core-concepts/facilitator
};
function createServer() {
const server = withX402(
new McpServer({ name: "PaidMCP", version: "1.0.0" }),
X402_CONFIG,
);
// Paid tool — $0.01 per call
server.paidTool(
"square",
"Squares a number",
0.01, // USD
{ number: z.number() },
{},
async ({ number }) => {
return { content: [{ type: "text", text: String(number ** 2) }] };
},
);
// Free tool
server.registerTool(
"echo",
{ description: "Echo a message", inputSchema: { message: z.string() } },
async ({ message }) => {
return { content: [{ type: "text", text: message }] };
},
);
return server;
}
const handler = createMcpHandler(createServer);
export default {
fetch(request, env, ctx) {
return handler(request, env, ctx);
},
} satisfies ExportedHandler;| 字段 | 描述 |
|---|---|
network |
生产环境用 base,测试用 base-sepolia |
recipient |
接收支付的钱包地址 |
facilitator |
支付 facilitator URL(使用 https://x402.org/facilitator) |
paidTool() 接受与注册工具相同的参数,外加价格:
| 参数 | 描述 |
|---|---|
name |
工具名称 |
description |
工具说明 |
price |
每次调用的价格,以美元计,例如 0.01。 |
inputSchema |
工具输入的 Zod 结构 |
annotations |
MCP 工具注释 |
handler |
支付成功后运行的异步函数 |
客户端在未支付的情况下调用付费工具时,服务器返回 402 及支付要求。客户端通过 x402 支付,携带支付凭证重试,并收到结果。
使用 base-sepolia,并从 Circle faucet ↗ 获取测试 USDC。
- 从 Agents SDK 支付 — 构建支付工具的客户端
- 对 HTTP 内容收费 — 对 HTTP 端点进行门控
- MCP 服务器指南 — 构建你的第一个 MCP 服务器