MCP Client with x402 Payment Support
This example demonstrates how to create an MCP (Model Context Protocol) client that can automatically pay for tool calls using the x402 payment protocol.
Overview
The client connects to an x402-enabled MCP server and:
- Discovers available tools
- Calls a free tool (ping)
- Calls a paid tool (get_weather) with automatic payment
- Shows how to check payment requirements before calling
Setup
- Copy
.env-localto.envand fill in your values:
cp .env-local .env
-
Configure environment variables:
EVM_PRIVATE_KEY: Your EVM wallet private key (must have testnet funds)MCP_SERVER_URL: MCP server URL (default: http://localhost:4022)
-
Install dependencies:
uv sync
Running
First, start the MCP server:
cd ../../servers/mcp
python main.py simple
Then run the client:
Simple Mode (Recommended)
Uses the wrap_mcp_client_with_payment_from_config factory function for easy setup:
python main.py simple
Advanced Mode
Uses x402MCPClient with manual setup for full control:
python main.py advanced
Advanced mode demonstrates:
- Manual MCP client and x402Client creation
- Client-side hooks (on_payment_required, on_before_payment, on_after_payment)
- Accessing underlying client instances
Expected Output
π 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
ββββββββββββββββββββββββββββββββββββββββββββββββββ
π Test 1: Calling free tool (ping)
ββββββββββββββββββββββββββββββββββββββββββββββββββ
Response: pong
Payment made: False
ββββββββββββββββββββββββββββββββββββββββββββββββββ
π° Test 2: Calling paid tool (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...
β
Demo complete!
Payment Flow
ββββββββββββββββ ββββββββββββββββ
β 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 β
βββββββββββββββββββββββββββββββββββββ
β β
Configuration Options
x402MCPClientOptions
x402_mcp = x402MCPClient(
mcp_client,
payment_client,
# Enable automatic payment (default: True)
auto_payment=True,
# Custom approval logic (optional)
on_payment_requested=lambda context: (
print(f"Pay {context.payment_required.accepts[0].amount}?"),
True # or False to deny
)[1],
)
Hooks
# Called before payment is made
x402_mcp.on_before_payment(lambda context: print(f"About to pay for: {context.tool_name}"))
# Called after payment settles
x402_mcp.on_after_payment(lambda context: print(f"Payment settled: {context.settle_response.transaction}"))