@1x402/mcp

@1x402/mcp

MCP server for 1x402 — gives an agent discover, list_providers, topup, route, call, and report_error as native tools instead of hand-rolled curl + signing code.

Runs locally, one process per agent host, over stdio — like @x402scan/mcp. The wallet lives on your machine and signs topup/route requests itself (via @1x402/sdk); the private key is never sent to 1x402.sh.

Install

Recommended (guided install)

npx @1x402/mcp install

Picks your client, writes its config file for you, and reports the wallet address + balance. Non-interactive: npx @1x402/mcp install --client cursor --yes (--client one of claude-code, codex, cursor, claude-desktop, vscode, windsurf, other; add --private-key 0x... to bring your own wallet instead of generating one).

Claude Code

claude mcp add 1x402 --scope user -- npx -y @1x402/mcp

Codex

codex mcp add 1x402 -- npx -y @1x402/mcp

(npx @1x402/mcp install --client codex does the same thing by writing [mcp_servers.1x402] into ~/.codex/config.toml directly.)

Manual (any client)

{
  "mcpServers": {
    "1x402": {
      "command": "npx",
      "args": ["-y", "@1x402/mcp"],
      "env": { "PRIVATE_KEY": "0x..." }
    }
  }
}

Cursor: same shape, under .cursor/mcp.json. Claude Desktop: claude_desktop_config.json. Codex uses TOML in ~/.codex/config.toml instead:

[mcp_servers.1x402]
command = "npx"
args = ["-y", "@1x402/mcp"]

Omit PRIVATE_KEY and the server generates a wallet on first run, persisted at ~/.1x402/mcp/wallet.json (0600 permissions). Fund that address with USDC on Base to use topup/route; discover/list_providers/get_wallet_info need no funds.

Tools

Tool	Cost	Purpose
get_wallet_info	free	This agent's wallet address + prepaid credit balance
discover	free	Semantic search over the index — describe the task, get ranked candidates
list_providers	free	Browse/filter the raw provider registry
topup	pays x402	Add prepaid USDC credits (Base mainnet)
route	debits credits	Call an endpoint (by category or id) through the toll booth — debits, pays the provider, relays the result; refunds on provider failure
call	pays x402	Pay a discovered provider directly with the wallet and call it — skips the toll booth and prepaid credits; no idempotency replay or auto-refund. Pass endpointId (from discover/list_providers) to also send a best-effort, gated outcome self-report — optional, never affects the call's own result
report_error	free	Emergency only. Report a critical bug in one of this MCP's own tools — not for recoverable errors (balance, network, 4xx), which already come back as { ok: false, error }

Config

env var	default
PRIVATE_KEY	none — falls back to the generated ~/.1x402/mcp/wallet.json
ONEX402_BASE_URL	https://1x402.sh/api

Develop

pnpm --filter @1x402/mcp build      # tsc -> dist/
pnpm --filter @1x402/mcp typecheck
node dist/index.js                  # runs the stdio server directly