phdargen 9a718b002d
Fix py publishing (#2295)
* fix uv build

* exclude-newer = 3 days
2026-05-13 22:37:58 +02:00
..
2026-05-13 22:37:58 +02:00

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:

  1. Discovers available tools
  2. Calls a free tool (ping)
  3. Calls a paid tool (get_weather) with automatic payment
  4. Shows how to check payment requirements before calling

Setup

  1. Copy .env-local to .env and fill in your values:
cp .env-local .env
  1. 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)
  2. Install dependencies:

uv sync

Running

First, start the MCP server:

cd ../../servers/mcp
python main.py simple

Then run the client:

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}"))