X402 MCP Template 🤖💰
Production-ready MCP server template for consuming X402-protected APIs with gasless micropayments
This template provides everything you need to create an MCP (Model Context Protocol) server that can consume X402-enabled APIs, enabling AI agents like Claude to make micropayment-based API calls seamlessly.
🤖 For AI Developers: See CLAUDE.md for comprehensive X402 + MCP integration documentation, payment flows, and AI development guidance.
✨ Features
- 🔐 X402 Gasless Micropayments - EIP-712 signatures, no gas fees for API consumption
- 🎭 Dual Mode Operation - Demo mode (no wallet) and Payment mode (with wallet)
- 🔍 Service Discovery - Automatic discovery of X402 API capabilities
- 🤖 Claude Desktop Ready - Drop-in integration with Claude Desktop
- 📡 MCP Inspector Compatible - Test and debug with MCP Inspector
- 🏭 Production-Ready - Mainnet (Base) and testnet (Base Sepolia) support
- 📝 Full TypeScript - Type-safe development with comprehensive types
- ⚡ Auto-Payment Handling - Automatic 402 retry with payment authorization
🏗️ Architecture
MCP + X402 Integration Flow
┌─────────────────────────────────────────────────────────────────────┐
│ Claude Desktop / MCP Client │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ User Request: "Search for coffee shops near me" │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ ↓ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ MCP Protocol: CallTool("search_places", {query: "coffee"}) │ │
│ └─────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────────┐
│ X402 MCP Server (This Template) │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ Tool Handler: Receives request │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ ↓ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ X402 Payment Client (x402-axios) │ │
│ │ - EIP-712 signature generation │ │
│ │ - Automatic 402 retry handling │ │
│ │ - Payment authorization │ │
│ └─────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────────┐
│ X402-Protected API Server │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ 1. First Request: Returns 402 Payment Required │ │
│ │ - Includes payment requirements (price, network, address) │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ ↓ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ 2. Payment Processing: │ │
│ │ - Verify EIP-712 signature │ │
│ │ - Submit to facilitator │ │
│ │ - Execute USDC transfer (gasless) │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ ↓ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ 3. Second Request: Payment authorized, returns data │ │
│ └─────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────────┐
│ Result Returned to Claude │
│ - API response data │
│ - Payment metadata │
│ - Cost information │
└─────────────────────────────────────────────────────────────────────┘
Key Points:
- MCP handles tool protocol and Claude communication
- x402-axios handles payment protocol automatically
- User only needs wallet with USDC - no manual payment steps
- All payment complexity is abstracted away
📁 Project Structure
Template-x402-Mcp/
├── index.ts # Main MCP server implementation
├── package.json # Dependencies and scripts
├── tsconfig.json # TypeScript configuration
├── .env.example # Environment variables template
├── README.md # This file - setup and usage guide
└── CLAUDE.md # AI-friendly X402 + MCP documentation
🚀 Quick Start
1. Clone and Setup
# Navigate to template directory
cd Template-x402-Mcp
# Install dependencies
npm install
# Copy environment variables
cp .env.example .env
2. Configure Environment
Edit .env file:
Option A: Demo Mode (No Payment)
# Leave PRIVATE_KEY empty or with placeholder
PRIVATE_KEY=<your-private-key-here>
# Set your X402 API endpoint
RESOURCE_SERVER_URL=https://places-api.x402hub.xyz
# Network (testnet for demo)
NETWORK=base-sepolia
Option B: Payment Mode (X402 Enabled)
# Add your wallet private key
PRIVATE_KEY=0x1234567890abcdef...
# Set your X402 API endpoint
RESOURCE_SERVER_URL=https://places-api.x402hub.xyz
# Network: base-sepolia (testnet) or base (mainnet)
NETWORK=base-sepolia
3. Customize Your Tools
Edit index.ts to define your API-specific tools:
// In ListToolsRequestSchema handler
{
name: "your_custom_tool",
description: "Description of what your tool does",
inputSchema: {
type: "object",
properties: {
// Define your input parameters
param1: {
type: "string",
description: "Parameter description"
}
},
required: ["param1"]
}
}
Add tool handler:
case "your_custom_tool": {
const { param1 } = args as { param1: string };
// Make X402-protected API call
const response = await client.post("/api/your-endpoint", {
param1: param1
});
return {
content: [{
type: "text",
text: JSON.stringify(response.data, null, 2)
}]
};
}
4. Build and Test
# Build TypeScript
npm run build
# Test with MCP Inspector
npm run inspector
# Or test in development mode
npm run dev
5. Claude Desktop Integration
Add to Claude Desktop configuration:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"x402-your-api": {
"command": "node",
"args": ["/absolute/path/to/Template-x402-Mcp/build/index.js"],
"env": {
"PRIVATE_KEY": "0x...",
"RESOURCE_SERVER_URL": "https://your-x402-api.example.com",
"NETWORK": "base-sepolia"
}
}
}
}
Restart Claude Desktop and your tools will be available!
🔑 Getting USDC for Testing
Testnet (Base Sepolia)
# Use Circle's testnet faucet
# Visit: https://faucet.circle.com/
# Enter your wallet address
# Receive free testnet USDC
Mainnet (Base)
Buy USDC on Base network through:
📖 Available Tools
Built-in Tools
| Tool | Description | Mode |
|---|---|---|
example_api_call | Template tool for X402 API calls | Both |
service_info | Get API service discovery metadata | Both |
health_check | Check API availability | Both |
Demo Mode: Returns sample data with setup instructions Payment Mode: Makes real X402-protected API calls
🎭 Demo Mode vs Payment Mode
Demo Mode (No Private Key)
Features:
- ✅ Works immediately without wallet setup
- ✅ Returns sample data for all tools
- ✅ Shows setup instructions in responses
- ✅ Perfect for development and testing MCP integration
- ❌ Cannot make real API calls
Use Cases:
- Testing MCP server functionality
- Developing tool definitions
- Claude Desktop integration testing
- Learning X402 protocol flow
Payment Mode (With Private Key)
Features:
- ✅ Makes real X402-protected API calls
- ✅ Automatic payment handling (no manual steps)
- ✅ Gasless USDC transfers
- ✅ Production-ready
- ⚠️ Requires USDC balance in wallet
Use Cases:
- Production AI agent deployments
- Real data consumption
- Paid API access
- Enterprise integrations
🛠️ Customization Guide
Adding a New Tool
Step 1: Add tool definition in ListToolsRequestSchema handler:
{
name: "get_data_by_id",
description: "Fetch specific data by ID from X402 API",
inputSchema: {
type: "object",
properties: {
id: {
type: "string",
description: "Unique identifier for the data"
}
},
required: ["id"]
}
}
Step 2: Add tool handler in CallToolRequestSchema handler:
case "get_data_by_id": {
const { id } = args as { id: string };
if (!id?.trim()) {
throw new McpError(ErrorCode.InvalidParams, "ID parameter is required");
}
// Demo mode fallback
if (!paymentEnabled) {
return {
content: [{
type: "text",
text: JSON.stringify({
demo_mode: true,
sample_data: { id, name: "Sample Data" },
setup_instructions: { /* ... */ }
}, null, 2)
}]
};
}
// Payment mode - real API call
const response = await client.get(`/api/data/${id}`);
return {
content: [{
type: "text",
text: JSON.stringify(response.data, null, 2)
}]
};
}
Changing API Endpoint
# In .env file
RESOURCE_SERVER_URL=https://your-new-api.example.com
Switching Networks
# Testnet (Base Sepolia)
NETWORK=base-sepolia
# Mainnet (Base)
NETWORK=base
🔍 Service Discovery
Your MCP server automatically fetches X402 service metadata from /.well-known/x402:
// Automatically called by service_info tool
const response = await axios.get(`${baseURL}/.well-known/x402`);
// Returns:
{
"service": "API Service Name",
"version": "1.0.0",
"payment": {
"protocol": "x402 v1.0",
"price": "$0.001",
"network": "base-sepolia"
},
"endpoints": {
"/api/endpoint": {
"method": "POST",
"description": "...",
"inputSchema": { /* ... */ },
"outputSchema": { /* ... */ }
}
}
}
Use this metadata to dynamically generate tools or provide API documentation to users.
🔐 Security Best Practices
- Never commit
.env- Use.env.exampleas template - Rotate private keys - Change keys regularly for production
- Use separate wallets - Different addresses for testnet/mainnet
- Monitor USDC balance - Track spending and set alerts
- Validate API responses - Check data integrity and structure
- Error handling - Don't expose sensitive info in errors
- Rate limiting - Implement client-side rate limits if needed
📊 Monitoring
Check Wallet Balance
Monitor your USDC balance and payment transactions:
- Testnet: Base Sepolia Explorer
- Mainnet: Base Explorer
Server Logs
# Development mode with logs
npm run dev
# Check payment status
# Logs show: ✅ Payment client initialized, wallet address, network
MCP Inspector
# Test tools interactively
npm run inspector
# Check:
# - Tool definitions are correct
# - Payment mode is active
# - API responses are valid
🧪 Testing
Test with MCP Inspector
# Start inspector
npm run inspector
# Test tools:
1. Select "service_info" - should return API metadata
2. Select "health_check" - should return API health status
3. Select your custom tools - should work in demo or payment mode
Test with Claude Desktop
- Add to config (see Claude Desktop Integration above)
- Restart Claude Desktop
- Test in conversation:
You: Can you check the service info for the X402 API? Claude: [Uses service_info tool, shows API metadata] You: Search for coffee shops near me Claude: [Uses your custom tool, makes payment if enabled]
Verify Payment Flow
Demo Mode:
- Tools return sample data
- Response includes setup instructions
- No USDC required
Payment Mode:
- First call triggers 402 response
- x402-axios automatically retries with payment
- USDC transferred (check explorer)
- Real data returned
🆘 Troubleshooting
"Running in DEMO MODE"
Issue: Private key not configured or invalid
Solutions:
- Check
.envfile has validPRIVATE_KEY=0x...(66 characters) - Ensure private key is not placeholder
<your-private-key-here> - Verify key format:
0xfollowed by 64 hex characters
"Payment Required: Insufficient USDC balance"
Issue: Wallet doesn't have enough USDC
Solutions:
- Get testnet USDC: https://faucet.circle.com/
- For mainnet, buy USDC on Base network
- Check balance in explorer (link above)
"Tool execution failed"
Issue: API endpoint or configuration problem
Solutions:
- Verify
RESOURCE_SERVER_URLis correct and accessible - Check if API supports X402 protocol
- Use
health_checktool to test connectivity - Use
service_infotool to verify API configuration
MCP Server Not Appearing in Claude
Issue: Claude Desktop not detecting MCP server
Solutions:
- Verify
build/index.jsexists:npm run build - Check Claude Desktop config has absolute path
- Restart Claude Desktop completely
- Check logs in Claude Desktop developer tools
📚 Resources
- X402 Protocol Documentation
- MCP Protocol Specification
- Base Network
- Coinbase Developer Platform
- EIP-712 Standard
- Circle USDC Faucet
📄 License
MIT License - see LICENSE file for details
🤝 Contributing
This is a template - fork it and make it your own!
- Clone the template
- Customize for your X402 API
- Deploy and share your MCP server
Built with ❤️ using X402 Protocol + Model Context Protocol
Replace this template with your own API integration and enable AI agents to consume your services! 🚀
