RoboNet x402 MCP Proxy

A production-ready proxy that connects MCP clients (Claude Desktop, Claude Code, Cursor, etc.) to x402-protected MCP servers with automatic micropayment handling.

What is this?

This proxy acts as a bridge between MCP clients and x402-protected MCP servers, automatically handling x402 micropayments for each tool call. It enables seamless integration with paid AI services through the Model Context Protocol (MCP).

Based on: Coinbase x402 MCP Example

Features

• 🔌 Universal MCP Client Support: Works with Claude Desktop, Claude Code, Cursor, and any MCP-compatible client
• 💰 Automatic Payments: Handles x402 micropayments transparently
• 🔄 Dynamic Tool Discovery: Automatically fetches and registers all available tools
• 📡 Real-time Progress Notifications: Streams SSE progress updates for long-running operations
• 🔐 Secure: Uses your wallet private key for payment signing
• ⚙️ Configurable: Customizable timeouts and settings via environment variables
• 🚀 Production-Ready: Error handling, logging, and graceful shutdown

Architecture

┌─────────────────────┐
│  MCP Client         │  Claude Desktop, Claude Code,
│  (stdio)            │  Cursor, or any MCP client
└──────────┬──────────┘
           │ MCP Protocol (stdio)
           ↓
┌─────────────────────┐
│  x402 MCP Proxy     │ ← This tool
│  (stdio ↔ HTTP)     │  Automatic payment handling
└──────────┬──────────┘
           │ HTTP + x402 payments
           ↓
┌─────────────────────┐
│  x402-Protected     │  Your MCP server with
│  MCP Server         │  paid tools/services
│  (FastAPI/HTTP)     │
└─────────────────────┘

Quick Start

Using with npx (Recommended)

No installation required! Just add to your MCP client config:

{
  "mcpServers": {
    "robonet": {
      "command": "npx",
      "args": ["-y", "@robonet/robonet-mcp"],
      "env": {
        "PRIVATE_KEY": "0x1234...",
        "SERVER_URL": "https://mcp.robonet.finance",
        "SERVER_ENDPOINT": "/mcp"
      }
    }
  }
}

Requirements:

• Node.js 18+
• A wallet with USDC on Base Sepolia (testnet) or Base (mainnet)
• An x402-protected MCP server to connect to

Local Development

For development or testing:

# Clone the repository
git clone https://github.com/robonet/robonet-x402-mcp-proxy.git
cd robonet-x402-mcp-proxy

# Install dependencies
npm install

# Configure environment variables
cp .env.example .env
# Edit .env with your settings

# Run in development mode
npm run dev

MCP Client Integration

This proxy works with any MCP-compatible client. Below are configuration examples for popular clients:

Claude Desktop

Add the proxy to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "robonet": {
      "command": "npx",
      "args": ["-y", "@robonet/robonet-mcp"],
      "env": {
        "PRIVATE_KEY": "0x1234...",
        "SERVER_URL": "https://mcp.robonet.finance",
        "SERVER_ENDPOINT": "/mcp"
      }
    }
  }
}

That's it! No installation required - npx will automatically download and run the latest version.

Claude Code

Claude Code (CLI) uses the same configuration format as Claude Desktop:

{
  "mcpServers": {
    "robonet": {
      "command": "npx",
      "args": ["-y", "@robonet/robonet-mcp"],
      "env": {
        "PRIVATE_KEY": "0x1234...",
        "SERVER_URL": "https://mcp.robonet.finance",
        "SERVER_ENDPOINT": "/mcp"
      }
    }
  }
}

Cursor IDE

Cursor supports MCP servers through its settings:

{
  "mcpServers": {
    "robonet": {
      "command": "npx",
      "args": ["-y", "@robonet/robonet-mcp"],
      "env": {
        "PRIVATE_KEY": "0x1234...",
        "SERVER_URL": "https://mcp.robonet.finance",
        "SERVER_ENDPOINT": "/mcp"
      }
    }
  }
}

Other MCP Clients

For any other MCP-compatible client that supports stdio transport:

1. Command: npx
2. Args: ["-y", "@robonet/robonet-mcp"]
3. Environment Variables:
   • PRIVATE_KEY: Your wallet private key (with USDC)
   • SERVER_URL: Your x402-protected MCP server URL
   • SERVER_ENDPOINT: The MCP endpoint path (usually /mcp)

The proxy uses stdio transport, making it compatible with any MCP client that supports process-based servers.

Usage

Once configured, restart your MCP client (Claude Desktop, Claude Code, Cursor, etc.). The proxy will:

1. ✅ Connect to your x402-protected MCP server
2. ✅ Automatically discover all available tools
3. ✅ Register them in your MCP client
4. ✅ Handle x402 payments for each tool call

You can then use the tools naturally in your conversations with the AI!

Examples

Example 1: RoboNet Trading Strategy Server

Connect to a trading strategy MCP server:

SERVER_URL=http://localhost:7284
SERVER_ENDPOINT=/mcp

Available tools:

• create_strategy - Create new trading strategies
• run_backtest - Run backtests
• get_all_strategies - List strategies
• And more...

See examples/basic/ for full setup.

Example 2: Generic x402 Server

Connect to any x402-protected MCP server:

SERVER_URL=https://api.example.com
SERVER_ENDPOINT=/mcp

The proxy will automatically discover and register all tools from the server.

How It Works

1. Tool Discovery

On startup, the proxy calls tools/list on your MCP server:

POST /mcp
{
  "jsonrpc": "2.0",
  "method": "tools/list"
}

2. Dynamic Registration

Each tool is registered in your MCP client with:

• Name
• Description
• Input schema (for validation)

3. Payment Handling

When your MCP client calls a tool:

1. MCP Client → Proxy: "call create_strategy with params X"
2. Proxy → Server: POST with x402 payment header
3. Server: Verifies payment, executes tool
4. Server → Proxy: Returns result
5. Proxy → MCP Client: Returns result

The x402-axios library automatically:

• Signs EIP-712 permits
• Adds X-PAYMENT header
• Retries if payment is required (402 response)

4. Response Handling

The proxy handles both:

• JSON-RPC responses (standard MCP)
• SSE streams (for long-running tools)

Environment Variables

| Variable | Required | Description | Default | Example | |----------|----------|-------------|---------|---------| | PRIVATE_KEY | ✅ | Wallet private key (with USDC) | - | 0x123... | | SERVER_URL | ✅ | Base URL of MCP server | - | https://mcp.robonet.finance | | SERVER_ENDPOINT | ✅ | MCP endpoint path | - | /mcp | | PAYMENT_TIMEOUT | ❌ | Payment timeout (seconds) | 1800 | 3600 | | REQUEST_TIMEOUT | ❌ | Request timeout (milliseconds) | 1200000 | 600000 |

Development

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build for production
npm run build

# Run production build
npm start

# Format code
npm run format

# Lint code
npm run lint

Troubleshooting

"Missing PRIVATE_KEY environment variable"

Make sure your .env file exists and contains a valid private key:

PRIVATE_KEY=0x1234567890abcdef...

"Could not connect to MCP server"

1. Check that your MCP server is running
2. Verify SERVER_URL is correct
3. Check firewall/network settings

"Payment verification failed"

1. Ensure your wallet has USDC on the correct network (Base Sepolia for testnet)
2. Check your private key is correct
3. Verify the server's payment requirements match your wallet capabilities

MCP client not seeing tools

1. Fully restart your MCP client (completely quit and reopen)
2. Check the proxy logs for errors
3. Verify your environment variables are correct
4. For Claude Desktop specifically: Cmd+Q to fully quit before reopening

Credits

Built on:

• Coinbase x402 - Micropayment protocol
• x402-axios - HTTP client with x402 support
• Model Context Protocol - Protocol specification

License

MIT

Support

• Website: RoboNet

Made with ❤️ by the RoboNet Team