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](./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 ```bash # 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)** ```env # 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)** ```env # 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:** ```typescript // 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:** ```typescript 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 ```bash # 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` ```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) ```bash # 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](https://www.coinbase.com/) - [Uniswap](https://app.uniswap.org/) - [Base Bridge](https://bridge.base.org/) ## 📖 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: ```typescript { 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: ```typescript 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 ```env # In .env file RESOURCE_SERVER_URL=https://your-new-api.example.com ``` ### Switching Networks ```env # Testnet (Base Sepolia) NETWORK=base-sepolia # Mainnet (Base) NETWORK=base ``` ## 🔍 Service Discovery Your MCP server automatically fetches X402 service metadata from `/.well-known/x402`: ```typescript // 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](https://sepolia.basescan.org/) - **Mainnet**: [Base Explorer](https://basescan.org/) ### Server Logs ```bash # Development mode with logs npm run dev # Check payment status # Logs show: ✅ Payment client initialized, wallet address, network ``` ### MCP Inspector ```bash # Test tools interactively npm run inspector # Check: # - Tool definitions are correct # - Payment mode is active # - API responses are valid ``` ## 🧪 Testing ### Test with MCP Inspector ```bash # 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](https://docs.cdp.coinbase.com/x402/docs/welcome) - [MCP Protocol Specification](https://modelcontextprotocol.io/) - [Base Network](https://base.org/) - [Coinbase Developer Platform](https://portal.cdp.coinbase.com/) - [EIP-712 Standard](https://eips.ethereum.org/EIPS/eip-712) - [Circle USDC Faucet](https://faucet.circle.com/) ## 📄 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! 🚀