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