* chore: version typescript packages * chore: version python package * chore: version go package * chore: update lock files
MCP Server with x402 Paid Tools
This example demonstrates how to create an MCP (Model Context Protocol) server with paid tools using the x402 payment protocol.
Overview
The server exposes:
- get_weather (paid) - Returns weather data for a city, costs $0.001
- ping (free) - Returns "pong", no payment required
Setup
- Copy
.env-localto.envand fill in your values:
cp .env-local .env
-
Configure environment variables:
EVM_ADDRESS: Your EVM wallet address to receive paymentsFACILITATOR_URL: x402 facilitator URL (default: https://x402.org/facilitator)PORT: Server port (default: 4022)
-
Install dependencies:
uv sync
Running
All examples use the create_payment_wrapper API - a lean, functional approach to adding payments to MCP tools.
Simple Mode (Recommended Starting Point)
Basic payment wrapper usage:
python main.py simple
Simple mode demonstrates:
- Creating a payment wrapper with shared configuration
- Wrapping tool handlers with payment logic
- Using native tool registration API
- Mixing paid and free tools
Advanced Mode (Production Features)
Payment wrapper with hooks for monitoring and control:
python main.py advanced
Advanced mode demonstrates:
- Server-side hooks for production features
on_before_execution: Rate limiting, access control (can abort)on_after_execution: Logging, metrics collectionon_after_settlement: Receipts, notifications
Existing Server Mode
Adding payment to an existing MCP server:
python main.py existing
Existing server mode demonstrates:
- Integrating x402 with an existing MCP server instance
- Minimal code changes to add payment
- Creating reusable payment wrappers
The server will start on http://localhost:4022 with:
- SSE endpoint:
GET /sse - Messages endpoint:
POST /messages - Health check:
GET /health
Testing
Use the MCP client example (examples/python/clients/mcp) to connect and test:
cd ../../clients/mcp
python main.py simple
Payment Flow
- Client calls
get_weathertool - Server returns 402 error with
PaymentRequireddata - Client creates payment payload and retries
- Server verifies payment, executes tool, returns result
- Payment is settled and receipt included in response
Architecture
┌─────────────────┐ ┌──────────────────┐ ┌──────────────────┐
│ MCP Client │────▶│ MCPServer │────▶│ x402Facilitator │
│ (with wallet) │ │ + PaymentWrapper │ │ (verification) │
│ │◀────│ (paid tools) │◀────│ (settlement) │
└─────────────────┘ └──────────────────┘ └──────────────────┘
The payment wrapper is a lightweight function that adds payment verification and settlement to individual tool handlers.