X402 Proxy MCP Server

readfetch MCP + x402 signing proxy

Most MCP hosts (Cursor, Claude Desktop, etc.) cannot attach PAYMENT-SIGNATURE on tools/call. This stdio MCP server lists tools from https://readfetch.com/mcp, executes tools/call against /v1/{endpoint} on the same host (so HTTP 402 triggers @x402/fetch payment), and signs retries automatically.

Requirements

• Node.js 20+
• A wallet on Base mainnet with a little USDC for paid tools (readfetch_text, …). tools/list does not load your key; the first tools/call does.
• Private key in env — never commit it

Cursor / Claude MCP config

{
  "mcpServers": {
    "readfetch": {
      "command": "npx",
      "args": ["-y", "@readfetch/mcp-x402-proxy@0.1.15"],
      "env": {
        "EVM_PRIVATE_KEY": "0xYOUR_KEY"
      }
    }
  }
}

From a checkout:

{
  "mcpServers": {
    "readfetch": {
      "command": "node",
      "args": ["/absolute/path/to/readfetch/tools/mcp-x402-proxy/index.mjs"],
      "env": {
        "EVM_PRIVATE_KEY": "0xYOUR_KEY"
      }
    }
  }
}

Optional: READFETCH_MCP_URL (default https://readfetch.com/mcp; https only for readfetch.com / www.readfetch.com, or localhost / 127.0.0.1 / [::1] with READFETCH_DEV=1). Upstream redirects are rejected. READFETCH_MAX_PAYMENT_USD (default 1, max 100) caps each x402 authorization. On readfetch.com upstream, payments must match READFETCH_EXPECTED_PAYTO (default catalog payee). READFETCH_DEV=1 is only for local MCP URLs and enables Sepolia there — never set it when READFETCH_MCP_URL points at production.

Wallet risk: any tool the model invokes (readfetch_crawl, batch, …) can spend USDC from your key until the wallet is empty (subject to the per-payment cap). Use a dedicated low-balance wallet.

Install from a checkout:

cd tools/mcp-x402-proxy
npm ci

npm ci in a git checkout uses the committed package-lock.json. npx @readfetch/mcp-x402-proxy installs exact dependency versions pinned in package.json (npm does not ship the lockfile in the published tarball).

Local smoke (checkout)

npm ci && npm test
npm run smoke                                    # readfetch_probe (free)
SMOKE_TOOL=readfetch_text npm run smoke          # paid REST path; needs Base USDC

From this directory — not the repo root:

cd tools/mcp-x402-proxy
npm login                    # user must own or belong to npm org @readfetch
npm publish --access public  # first publish of a scoped package

Wrong: npm publish @readfetch/mcp-x402-proxy from ReadFetch/ (404 — nothing to publish there).

If the @readfetch org does not exist on npmjs.com, create it or temporarily change name in package.json to an unscoped name you control.

Default tool path

1. readfetch_probe with { "url": "…" } (free; may include preview ~400 chars when HTML, not a bot wall)
2. readfetch_text with the same url
3. If probe reports challenge: true, use readfetch_scrape (then readfetch_scrape_residential if needed)

Feedback (integration issues)

After a confusing 402, MCP result, or doc mismatch, call readfetch_feedback (free — no EVM_PRIVATE_KEY) with:

{ "request_id": "<X-Request-Id from that call>", "category": "integration", "message": "…" }

Paid delivery disputes use POST /v1/claims, not feedback. Details: readfetch.com/docs#feedback.

Without this proxy

• REST: awal x402 pay https://readfetch.com/v1/text -d '{"url":"…"}' or @x402/fetch in your app
• Direct MCP URL: only works if your host can set payment headers on the HTTP request to /mcp

See also readfetch integrations and SKILL.md.

Directory: Official MCP Registry io.github.readfetch/mcp-x402-proxy · Glama listing steps in readfetch/readfetch docs/GLAMA.md (operator).