x402-mcp 0.3.0

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 returns payment details (amount, network, recipient)
    → Agent shows details to user, user approves
    → Agent calls x402_fetch(url, confirm_payment=True)
    → x402-mcp signs a gasless EIP-712 payment authorization
    → Agent gets the response ✓

By default, your agent confirms payments with the user before paying. Set X402_CONFIRM_PAYMENTS=false to auto-pay without confirmation (original behavior).

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",
        "X402_CONFIRM_PAYMENTS": "true"
      }
    }
  }
}

Your agent now has two tools:

Tool	Description
x402_fetch	HTTP requests to any URL — shows payment details for confirmation, then pays on approval
wallet_info	Returns your wallet's public address for funding/verification

Usage examples

Fetch from an x402-gated API (with payment confirmation):

# Step 1: Agent makes request, gets payment details
x402_fetch(url="https://api.example.com/data")
# → Returns: {payment_required: True, human_readable: {amount: "1000000", ...}}

# Step 2: After user approves, agent confirms payment
x402_fetch(url="https://api.example.com/data", confirm_payment=True)
# → Returns: {status: 200, body: "..."}

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