x402-mcp 0.2.1

MCP tools for AI agents — HTTP requests with automatic x402 micropayments

x402-mcp

Give your AI agent a wallet. It pays for APIs automatically.

x402-mcp is an MCP server that adds HTTP request tools with automatic x402 micropayments to any AI agent. When a request hits a 402-gated endpoint, payment happens automatically — no API keys, no accounts, no billing dashboards.

Works with any x402-enabled service. Not locked to a single provider.

How it works

Agent calls x402_fetch("https://some-api.com/data")
    → Server responds 402 Payment Required
    → x402-mcp signs a gasless EIP-712 payment authorization
    → Request retries with payment header
    → Agent gets the response ✓

Your agent never sees the payment flow. It just makes requests and gets responses.

Quick start

# Install and run the setup wizard
uvx x402-mcp-setup

The wizard will:

1. Generate a fresh EVM wallet (or use your existing key with --key)
2. Show a QR code for your wallet address
3. Print funding instructions (testnet USDC is free)
4. Output the MCP config JSON, ready to paste

Add to your MCP client

Paste the config into ~/.claude/mcp.json (Claude Code) or your Cursor MCP settings:

{
  "mcpServers": {
    "x402-mcp": {
      "command": "uvx",
      "args": ["x402-mcp"],
      "env": {
        "EVM_PRIVATE_KEY": "0xYourPrivateKey"
      }
    }
  }
}

Your agent now has two tools:

Tool	Description
x402_fetch	HTTP requests to any URL — pays 402 responses automatically
wallet_info	Returns your wallet's public address for funding/verification

Usage examples

Fetch from an x402-gated API:

x402_fetch(url="https://api.example.com/data")

POST with JSON body:

x402_fetch(
    url="https://api.example.com/submit",
    method="POST",
    headers={"Content-Type": "application/json"},
    body='{"query": "hello"}'
)

Check your wallet address:

wallet_info()

Architecture

src/x402_mcp/
├── mcp_server.py   # FastMCP server — x402_fetch + wallet_info tools
└── setup.py        # Wallet generation wizard, prints MCP config JSON

Two entry points:

• x402-mcp — MCP stdio server (what your agent connects to)
• x402-mcp-setup — Interactive setup wizard

The server lazy-initializes an x402HttpxClient on first tool call. Payments are gasless EIP-712 signed authorizations — no on-chain transaction per request. Binary responses (images, etc.) are returned as base64-encoded data.

Development

uv sync --extra dev    # Install deps
uv run ruff check src/ # Lint
uv run pytest tests/ -v # Test

E2E test against a real x402 endpoint:

EVM_PRIVATE_KEY=0x... X402_TEST_URL=https://some-x402-api.com/endpoint \
  uv run python scripts/test_e2e.py

License

MIT