# Template-x402-Mcp
## 基本信息
- Slug: `codalabs-xyz-template-x402-mcp`
- Source: modelscope
- Publisher: @CodaLabs-xyz/Template-x402-Mcp
- Categories: blockchain / 金融 / app-automation
- Hosted: No
- License: Unknown
- Source URL: https://www.modelscope.cn/mcp/servers/@CodaLabs-xyz/Template-x402-Mcp
## 简介
暂无描述。
## 安装提示

```bash
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
```

## MCP Server 详情

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