Skip to main content
Glama

X402 MCP Template

by CodaLabs-xyz
GitHub
JavaScript
  • Apple
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

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

// 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

  1. Never commit - 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:

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

📄 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! 🚀

Deploy Server
-
security - not tested
F
license - not found
-
quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Tools

Production-ready MCP server template for consuming X402-protected APIs with gasless micropayments. Enables AI agents like Claude to make micropayment-based API calls seamlessly using EIP-712 signatures and USDC transfers.

  1. ✨ Features
    1. 🏗️ Architecture
      1. MCP + X402 Integration Flow
    2. 📁 Project Structure
      1. 🚀 Quick Start
        1. 1. Clone and Setup
        2. 2. Configure Environment
        3. 3. Customize Your Tools
        4. 4. Build and Test
        5. 5. Claude Desktop Integration
      2. 🔑 Getting USDC for Testing
        1. Testnet (Base Sepolia)
        2. Mainnet (Base)
      3. 📖 Available Tools
        1. Built-in Tools
      4. 🎭 Demo Mode vs Payment Mode
        1. Demo Mode (No Private Key)
        2. Payment Mode (With Private Key)
      5. 🛠️ Customization Guide
        1. Adding a New Tool
        2. Changing API Endpoint
        3. Switching Networks
      6. 🔍 Service Discovery
        1. 🔐 Security Best Practices
          1. 📊 Monitoring
            1. Check Wallet Balance
            2. Server Logs
            3. MCP Inspector
          2. 🧪 Testing
            1. Test with MCP Inspector
            2. Test with Claude Desktop
            3. Verify Payment Flow
          3. 🆘 Troubleshooting
            1. "Running in DEMO MODE"
            2. "Payment Required: Insufficient USDC balance"
            3. "Tool execution failed"
            4. MCP Server Not Appearing in Claude
          4. 📚 Resources
            1. 📄 License
              1. 🤝 Contributing

                New MCP Servers

                MCP directory API

                We provide all the information about MCP servers via our MCP API.

                curl -X GET 'https://glama.ai/api/mcp/v1/servers/CodaLabs-xyz/Template-x402-Mcp'

                If you have feedback or need assistance with the MCP directory API, please join our Discord server