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 ava…