x402scan-mcp

MCP server for calling x402-protected APIs with automatic payment handling.

Install

Claude Code

claude mcp add x402scan -- npx -y x402scan-mcp@latest

Codex

codex mcp add x402scan -- npx -y x402scan-mcp@latest

Cursor

Claude Desktop

Codex - Add to ~/.codex/config.toml:

[mcp_servers.x402scan]
command = "npx"
args = ["-y", "x402scan-mcp@latest"]

Cursor - Add to .cursor/mcp.json:

{
  "mcpServers": {
    "x402scan": {
      "command": "/bin/bash",
      "args": ["-c", "source $HOME/.nvm/nvm.sh 2>/dev/null; exec npx -y x402scan-mcp@latest"]
    }
  }
}

Claude Desktop - Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "x402scan": {
      "command": "/bin/bash",
      "args": ["-c", "source $HOME/.nvm/nvm.sh 2>/dev/null; exec npx -y x402scan-mcp@latest"]
    }
  }
}

Usage

On first run, a wallet is generated at ~/.x402scan-mcp/wallet.json. Deposit USDC on Base to the wallet address before making paid API calls.

Workflow:

1. check_balance - Check wallet and get deposit address
2. query_endpoint - Probe endpoint for pricing/schema (optional)
3. execute_call - Make the paid request

Tools (4)

| Tool | Description | |------|-------------| | check_balance | Get wallet address and USDC balance | | query_endpoint | Probe x402 endpoint for pricing/schema without payment | | validate_payment | Pre-flight check if payment would succeed | | execute_call | Make paid request to x402 endpoint |

Environment

| Variable | Description | |----------|-------------| | X402_PRIVATE_KEY | Override wallet (optional) | | X402_DEBUG | Set to true for verbose logging |

Supported Networks

Base, Base Sepolia, Ethereum, Optimism, Arbitrum, Polygon (via CAIP-2)

Develop

bun install

# Add local server to Claude Code
claude mcp add x402scan-dev -- bun run /path/to/x402scan-mcp/src/index.ts

# Build
bun run build

# Build .mcpb for Claude Desktop
bun run build:mcpb