X402 MCP Template 🤖💰

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.jsonWindows: %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:

• Coinbase
• Uniswap
• Base Bridge

📖 Available Tools

Built-in Tools

Demo Mode: Returns sample data with setup instructionsPayment 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

1. Never commit .env - Use .env.example as template
2. Rotate private keys - Change keys regularly for production
3. Use separate wallets - Different addresses for testnet/mainnet
4. Monitor USDC balance - Track spending and set alerts
5. Validate API responses - Check data integrity and structure
6. Error handling - Don't expose sensitive info in errors
7. 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

1. Add to config (see Claude Desktop Integration above)
2. Restart Claude Desktop
3. 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:

1. Check .env file has valid PRIVATE_KEY=0x... (66 characters)
2. Ensure private key is not placeholder <your-private-key-here>
3. Verify key format: 0x followed by 64 hex characters

"Payment Required: Insufficient USDC balance"

Issue: Wallet doesn't have enough USDC

Solutions:

1. Get testnet USDC: https://faucet.circle.com/
2. For mainnet, buy USDC on Base network
3. Check balance in explorer (link above)

"Tool execution failed"

Issue: API endpoint or configuration problem

Solutions:

1. Verify RESOURCE_SERVER_URL is correct and accessible
2. Check if API supports X402 protocol
3. Use health_check tool to test connectivity
4. Use service_info tool to verify API configuration

MCP Server Not Appearing in Claude

Issue: Claude Desktop not detecting MCP server

Solutions:

1. Verify build/index.js exists: npm run build
2. Check Claude Desktop config has absolute path
3. Restart Claude Desktop completely
4. 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!

1. Clone the template
2. Customize for your X402 API
3. 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! 🚀