X402 Proxy

A local MCP (Model Context Protocol) proxy that connects to remote MCP servers and automatically handles x402 payments. When a remote MCP tool triggers an HTTP 402 response, the proxy signs a USDC payment on-chain and retries — transparently, with no changes needed on the client side.

How It Works

┌─────────────┐      stdio       ┌──────────────┐    HTTP + x402     ┌──────────────┐
│  AI Client   │ ◄──────────────► │  x402 Proxy  │ ◄────────────────► │ Remote MCP A │
│ (Claude, etc)│                  │  (this repo)  │                   ├──────────────┤
└─────────────┘                  │              │ ◄────────────────► │ Remote MCP B │
                                  └──────────────┘                   └──────────────┘

1. The proxy connects to one or more remote MCP servers (via Streamable HTTP or SSE).
2. It discovers their tools and re-exposes them to the AI client over stdio, prefixed by server name (e.g. cmc_get_quotes).
3. When a tool call returns HTTP 402, the proxy intercepts it, signs an EIP-3009 transferWithAuthorization (USDC on Base), and retries automatically.

Quick Start

1. Install

git clone https://github.com/coinmarketcap-official/x402-mcp-proxy.git
cd x402-mcp-proxy
pnpm install

2. Configure Remote MCPs

Create x402-mcps.json in the project root (see x402-mcps.example.json):

{
  "x402mcpServers": [
    {
      "url": "https://pro.coinmarketcap.com/x402/mcp",
      "prefix": "cmc"
    },
    {
      "url": "https://other-mcp.example.com/mcp",
      "prefix": "other",
      "headers": {
        "Authorization": "Bearer your_token"
      }
    }
  ]
}

Or pass it as an environment variable (prefix, url pairs):

export X402_REMOTE_MCPS="cmc,https://pro.coinmarketcap.com/x402/mcp"

3. Configure Wallet

Copy .env.example to .env and add at least one private key:

cp .env.example .env

EVM_PRIVATE_KEY=0xYOUR_PRIVATE_KEY_HERE

The EVM wallet needs USDC on Base for x402 payments. Solana (SVM) is also supported.

4. Run

pnpm dev    # development (tsx)
pnpm build && pnpm start  # production

5. Connect from an AI Client

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "x402": {
      "command": "npx",
      "args": ["tsx", "/path/to/x402-mcp-proxy/src/index.ts"],
      "env": {
        "EVM_PRIVATE_KEY": "0x...",
        "X402_REMOTE_MCPS": ["cmc", "https://pro.coinmarketcap.com/x402/mcp"]
      }
    }
  }
}

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "x402": {
      "command": "npx",
      "args": ["tsx", "/path/to/x402-mcp-proxy/src/index.ts"],
      "env": {
        "EVM_PRIVATE_KEY": "0x...",
        "X402_REMOTE_MCPS": ["cmc", "https://pro.coinmarketcap.com/x402/mcp"]
      }
    }
  }
}

You can also point to a config file for more advanced options (custom headers, etc.):

"X402_CONFIG": "/path/to/x402-mcps.json"

Configuration Reference

Remote MCP Servers

Source	Description
X402_REMOTE_MCPS env	Flat pair list: ["prefix","url",…] or "prefix,url,…" (takes priority)
X402_CONFIG env	Custom path to a JSON config file
x402-mcps.json	Default config file in project root

Env var format — prefix/url pairs, no headers support:

["cmc", "https://pro.coinmarketcap.com/x402/mcp"]

Config file format — full control with headers:

{
  "x402mcpServers": [
    {
      "prefix": "cmc",
      "url": "https://pro.coinmarketcap.com/x402/mcp"
    },
    {
      "prefix": "other",
      "url": "https://other.example.com/mcp",
      "headers": { "Authorization": "Bearer xxx" }
    }
  ]
}

Wallet Keys

Env Variable	Description
EVM_PRIVATE_KEY	EVM private key (0x-prefixed hex). Used for USDC payments on Base.
SVM_PRIVATE_KEY	Solana private key (base58-encoded). Used for USDC payments on Solana.

At least one key is required for x402 payment handling.

Payment Safety Limits

The proxy validates every 402 payment request before signing. All limits are configurable via environment variables:

Env Variable	Default	Description
X402_MAX_PAYMENT	100000 (0.10 USDC)	Maximum amount per single request (in asset smallest unit)
X402_MAX_SPEND_PER_SESSION	1000000 (1.00 USDC)	Maximum cumulative spend per proxy session
X402_ALLOWED_NETWORKS	eip155:8453,solana:5eykt…	Comma-separated allowlist of CAIP-2 network IDs
X402_ALLOWED_ASSETS	Base USDC, Solana USDC	Comma-separated allowlist of asset contract addresses

If a 402 response requests an amount, network, or asset outside these limits, the proxy rejects the payment and returns the raw 402 to the client without signing anything. Session spend resets when the proxy process restarts.

What is x402?

x402 is an open protocol by Coinbase that enables instant, pay-per-request API access using stablecoin payments over HTTP. When an API returns HTTP 402, the client signs a USDC transfer authorization, and the server's facilitator executes the on-chain payment only after successfully delivering the response.

Key properties:

• No subscription needed — pay per request with USDC
• Pay only on success — if the server fails to return data, the signed authorization expires unused and no payment is deducted
• Works on Base (EVM) and Solana

Project Structure

x402-mcp-proxy/
├── src/index.ts           # Proxy entry point
├── x402-mcps.example.json # Example remote MCP config
├── .env.example           # Example environment variables
├── package.json
├── tsconfig.json
└── LICENSE                # MIT

Security Considerations

Trust Model

This proxy is designed to run locally on your own machine as a stdio-based MCP server. The AI client (Claude, Cursor, etc.) communicates with it over stdin/stdout — there is no network listener. Authentication between the client and the proxy is therefore handled by OS-level process isolation.

If you deploy this proxy in a shared or multi-user environment (e.g., a server accessed by multiple users), you should add an authentication layer in front of it. The default stdio transport is not designed for that use case.

Private Key Storage

Private keys are loaded from environment variables (typically a .env file). For personal / development use this is acceptable, but for production or high-value wallets consider:

• OS keychain integration (macOS Keychain, Linux secret-service)
• Hardware wallets or cloud KMS (AWS KMS, GCP Cloud KMS)
• Encrypted env files with a passphrase

Never commit .env files containing real private keys to version control.

Built-in Protections

The proxy ships with several safety checks enabled by default:

• Per-request amount cap — rejects 402 responses that request more than the configured limit
• Session spending cap — stops signing once cumulative spend reaches the threshold
• Network & asset allowlists — only pays on explicitly permitted chains and tokens
• HTTPS enforcement — warns at startup if any remote MCP URL uses an insecure protocol (non-localhost HTTP)
• Sanitised error output — internal error details are not leaked to clients
• Structured payment audit log — every signed payment is logged to stderr with amount, network, asset, recipient, and target URL

License

MIT