x402 自动支付 MCP 客户端实战为 MCP 工具调用接入链上结算【免费下载链接】x402A payments protocol for the internet. Built on HTTP.项目地址: https://gitcode.com/GitHub_Trending/x4/x402导读本文以仓库中的官方示例 examples/python/clients/mcp/README.md 为主体讲解如何在 Python 中构建一个支持 x402 支付协议的 MCPModel Context Protocol客户端当调用需要付费的 MCP 工具时客户端能自动识别服务端返回的 402 PaymentRequired 响应、自动构造支付载荷、重试调用并在成功后退款与出具收据。读完本文你将掌握x402MCPClient的两种接入方式Simple / Advanced、三个客户端侧钩子hook的用法以及从工具发现、免费工具调用到付费工具自动支付的完整调用链。背景为什么 MCP 工具需要 x402 支付MCP 是连接 LLM 应用与外部工具的标准化协议但传统 MCP 服务端无法对工具调用收费。x402 将 HTTP 402 Payment Required 语义与链上结算结合服务端声明某工具需要支付例如get_weather收费 $0.001客户端首次调用收到 402 响应后基于收到的PaymentRequired数据创建并签署支付载荷重试调用时随工具参数一并提交服务端验证、执行并结算后把结算凭证SettleResponse随结果返回。本示例对应仓库中的配套服务端 examples/python/servers/mcp/README.md它暴露两个工具收费的get_weather与免费的ping。客户端示例的目标就是透明地处理这种先 402、再付费重试的交互让上层应用像调用普通工具一样调用付费工具。环境准备与项目结构示例位于examples/python/clients/mcp/核心文件如下文件作用main.py入口根据命令行参数simple/advanced路由到对应示例simple.pySimple 模式使用真实 MCP SDK 的推荐接入方式advanced.pyAdvanced 模式手动组装并注册全部钩子pyproject.toml依赖声明采用 uv 管理README.md官方使用说明本文主体复制环境变量文件cp .env-local .env然后编辑.env填入以下值环境变量说明默认值EVM_PRIVATE_KEYEVM 钱包私钥测试网需有资金用于签名支付载荷无必填MCP_SERVER_URLMCP 服务端地址http://localhost:4022从源码看simple.py 与 advanced.py 都通过os.getenv读取这两个变量并在私钥缺失时直接报错退出EVM_PRIVATE_KEY environment variable is required。MCP_SERVER_URL的默认值http://localhost:4022与配套服务端的默认端口一致。安装依赖uv syncpyproject.toml 中声明了三个依赖x402[mcp,evm]x402 Python SDK通过 extra 同时引入 MCP 集成与 EVM 机制python-dotenv1.0.0加载.env环境变量httpx0.27.0HTTP 底层依赖。注意其[tool.uv.sources]将x402指向仓库内../../../../python/x402editable 安装即直接使用当前仓库的 SDK 源码。第一步启动 MCP 服务端客户端示例需要先有一个 x402 启用的 MCP 服务端cd ../../servers/mcp python main.py simple服务端将在http://localhost:4022启动提供SSE 端点GET /sse消息端点POST /messages健康检查GET /health第二步运行客户端Simple 模式推荐回到客户端目录执行python main.py simpleREADME 将 Simple 模式描述为使用wrap_mcp_client_with_payment_from_config工厂函数快速装配需要说明的是simple.py 的实际实现采用了等价的手动装配路线分为四个步骤创建钱包账户Account.from_key(EVM_PRIVATE_KEY)还原 EVM 账户创建支付客户端实例化x402ClientSync()并通过register_exact_evm_client(payment_client, EthAccountSigner(account))注册 Exact EVM 结算方案连接 MCP 服务端用官方mcpSDK 通过 SSE 传输建立ClientSession并完成initialize()握手封装成MCPClientAdapter将 SDK 会话适配为x402MCPClient所需的接口装配x402MCPClient传入适配器与支付客户端设置auto_paymentTrue和on_payment_requested回调随后即可像普通客户端一样调用call_tool。若不想手写适配器SDK 在 client_async.py 中提供了wrap_mcp_client_with_payment_from_config(mcp_client, schemes, auto_paymentTrue, ...)与create_x402_mcp_client_from_config(mcp_client, config)两个工厂函数可直接基于schemes注册列表如{network: eip155:84532, client: ExactEvmClientScheme(signer)}一键完成装配其测试见 tests/test_client.py。Simple 模式演示了三件事调用免费工具ping、调用付费工具get_weather并自动支付、读取支付收据。第三步运行客户端Advanced 模式完全控制python main.py advancedAdvanced 模式在 Simple 模式基础上额外演示手动创建底层客户端显式创建x402ClientSync并注册 EVM 方案便于替换自定义配置三个客户端侧钩子on_payment_required收到 402 时触发可查看支付选项数量、on_before_payment创建支付前触发、on_after_payment支付提交后触发可读取交易哈希访问底层实例通过x402_mcp.client与x402_mcp.payment_client属性直接访问被包装的 MCP 客户端与支付客户端advanced.py。这两个入口由 main.py 依据第一个命令行参数路由缺省时默认走simple。预期输出解读官方 README 给出了完整运行输出关键片段如下 Connecting to MCP server at: http://localhost:4022 Using wallet: 0x... ✅ Connected to MCP server Discovering available tools... Available tools: - get_weather: Get current weather for a city. Requires payment of $0.001. - ping: A free tool that returns pong免费工具ping返回pong且Payment made: False证明免费工具不会被误扣费付费工具get_weather则输出 Payment required for tool: get_weather Amount: 1000 (0x036CbD53842c5426634e7929541eC2318f3dCF7e) Network: eip155:84532 Approving payment... Response: {city: San Francisco, weather: sunny, temperature: 65} Payment made: True Payment Receipt: Success: True Transaction: 0x...其中Amount: 1000表示以最小单位计价如 1000 wei 的报价实际示例服务端定价为 $0.001括号内是收款资产合约地址Network: eip155:84532是 Base 测试网链标识。支付成功后结果中携带SettleResponse包含Success与Transaction字段。支付流程一次付费工具调用的完整生命周期README 给出了八步时序图概括如下┌──────────────┐ ┌──────────────┐ │ MCP Client │ │ MCP Server │ └──────┬───────┘ └──────┬───────┘ │ 1. callTool(get_weather) │ │──────────────────────────────────▶│ │ 2. 402 PaymentRequired │ │◀──────────────────────────────────│ │ 3. createPaymentPayload() │ │ (signs transaction) │ │ 4. callTool PaymentPayload │ │──────────────────────────────────▶│ │ 5. verify() │ │ 6. execute() │ │ 7. settle() │ │ 8. Result SettleResponse │ │◀──────────────────────────────────│结合源码可以看清客户端一侧的每一步实现client_async.py 的call_tool方法首次无支付调用call_tool以{name: ..., arguments: ...}发起调用识别 402通过extract_payment_required_from_result判断是否为付费要求优先解析structuredContent回退到解析content[0].text中的 JSON兼容 FastMCP 包装的错误格式触发钩子若注册了on_payment_required钩子则先行执行钩子可返回PaymentRequiredHookResult(payment..., abort...)直接注入支付载荷或中止流程审批与签名若auto_paymentTrue调用on_payment_requested回调获得用户审批随后通过支付客户端create_payment_payload(payment_required)生成并签署支付载荷序列化后放入_meta的x402/payment键常量定义见 types.py带支付重试再次调用工具服务端完成verify()验证、execute()执行工具、settle()结算提取收据从返回结果的_meta的x402/payment-response键中解析SettleResponse封装为MCPToolCallResult(content, is_error, payment_response, payment_made)返回。值得注意若auto_paymentFalse且未注册任何处理钩子付费调用将抛出PaymentRequiredErrorSDK 在构造时会发出 warning 提醒这为需要人工确认或企业审批的场景保留了控制点。配置选项与钩子详解x402MCPClient 构造参数x402_mcp x402MCPClient( mcp_client, # 已连接的真实 MCP 客户端此处为 adapter 包装的 ClientSession payment_client, # 已注册方案的 x402 支付客户端x402ClientSync / x402ClientAsync auto_paymentTrue, # 是否自动创建并提交支付默认 True on_payment_requestedlambda context: ( print(fPay {context.payment_required.accepts[0].amount}?), True # 返回 False 则拒绝支付 )[1], )各参数说明与 client_async.py 的构造函数一一对应参数含义默认值mcp_client底层 MCP 客户端需实现call_tool(params, **kwargs)必填payment_clientx402 支付客户端负责生成支付载荷必填auto_payment是否自动支付关闭后付费调用需由钩子接管Trueon_payment_requested支付前审批回调返回True放行、False拒绝None三个客户端侧钩子# 收到 402 时触发支付前可用于查看支付选项、实现缓存 x402_mcp.on_payment_required(lambda context: print(f Payment required for: {context.tool_name})) # 创建支付前触发可用于日志 x402_mcp.on_before_payment(lambda context: print(fAbout to pay for: {context.tool_name})) # 支付结算后触发可打印交易哈希 x402_mcp.on_after_payment(lambda context: print(fPayment settled: {context.settle_response.transaction}))钩子对应上下文类型定义在 types.py 中PaymentRequiredContext含tool_name、arguments、payment_required与AfterPaymentContext含tool_name、payment_payload、result、settle_response。三个注册方法均返回self支持链式调用。与配套服务端联调验证完整跑通本示例需要服务端与客户端配合。服务端示例examples/python/servers/mcp/README.md同样支持simple/advanced/existing三种模式其中advanced模式的服务端钩子on_before_execution限流与访问控制、on_after_execution日志与指标、on_after_settlement收据与通知与本文客户端的三个钩子一一对应形成客户端审批 服务端控制的完整闭环。服务端 README 还推荐直接使用本文示例进行联调cd ../../clients/mcp python main.py simple总结本文完整演示了 x402 自动支付 MCP 客户端的搭建、运行与原理从.env配置、uv sync安装、启动配套服务端到 Simple / Advanced 两种模式的差异与选择同时结合 SDK 源码client_async.py、client.py、types.py剖析了首次调用 → 识别 402 → 审批签名 → 带支付重试 → 解析收据的底层调用链。对于希望将 AI 工具调用从免费试用升级为按次计费的开发者这个示例是理解 MCP x402 集成的最小可运行范本也是后续实现支付缓存、限流、动态定价DynamicPrice/DynamicPayTo定义见 types.py等生产特性的起点。【免费下载链接】x402A payments protocol for the internet. Built on HTTP.项目地址: https://gitcode.com/GitHub_Trending/x4/x402创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
