MCP server for calling x402-protected APIs with automatic payment handling.
Overview
MCP server for calling x402-protected APIs with automatic payment handling. - Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows): 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. 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 Base, Base Sepolia, Ethereum, Optimism, Arbitrum, Polygon (via CAIP-2)
README
x402scan-mcp
MCP server for calling x402-protected APIs with automatic payment handling.
Install
Claude Code
claude mcp add x402scan --scope user -- npx -y x402scan-mcp@latest
Codex
codex mcp add x402scan -- npx -y x402scan-mcp@latest
Cursor
Claude Desktop
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:
check_balance- Check wallet and get deposit addressquery_endpoint- Probe endpoint for pricing/schema (optional)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
Install
This server does not publish a one-line install command.
Open the repository installation guide New to MCP? Start with the mcpskill.org guide →Configuration
{
"mcpServers": {
"x402scan": {
"command": "/bin/bash",
"args": ["-c", "source $HOME/.nvm/nvm.sh 2>/dev/null; exec npx -y x402scan-mcp@latest"]
}
}
}