Skip to main content
Glama
@readfetch/mcp-x402-proxy

@readfetch/mcp-x402-proxy

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

Related MCP server: x402 MCP Proxy

Cursor / Claude MCP config

{
  "mcpServers": {
    "readfetch": {
      "command": "npx",
      "args": ["-y", "@readfetch/mcp-x402-proxy@latest"],
      "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; returns the full extracted text for the first 3 probes per IP per day, a preview of ~400 chars after that)

  2. readfetch_text with the same url

  3. If probe reports challenge: true, use readfetch_scrape (then readfetch_scrape_residential if needed)

No wallet yet?

readfetch_text, readfetch_scrape, readfetch_section and readfetch_diff fall back to the free probe when neither EVM_PRIVATE_KEY nor X402_BUYER_KEY is set. The result carries the same content plus a leading note and _meta.free_trial: true, so an installed-but-unfunded host still gets a page instead of an error about a private key. The fallback does not exist for screenshot, pdf, batch, crawl or fetch — a probe cannot produce those — and a malformed key still errors rather than silently downgrading.

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 com.readfetch/mcp-x402-proxy · Glama listing steps in readfetch/readfetch docs/GLAMA.md (operator).

Policies

Both are required by the Claude and ChatGPT MCP directories; the Official Registry entry carries the same links in /.well-known/mcp.json and service.json.

Available Tools

15 tools
readfetch_batchA
Read-only
Inspect

Paid routes require a funded Base USDC wallet. Use readfetch-client / @readfetch/client or the MCP signing proxy (@readfetch/mcp-x402-proxy). Direct calls without a signing client will stop at 402. Read a fixed list of public HTML pages in one call—the same article extraction as POST /v1/text for each URL (Markdown or plain text plus title and metadata). One x402 payment covers the batch (minimum 3 pages quoted; URLs deduped, max 50). Returns results in input order: each item has url, status_code, text, billed, and hint when undelivered, plus batch-level delivered, failed, billed_pages, and optional credit for unused pages. Undelivered pages are not billed. Use readfetch_text for one URL, readfetch_map then readfetch_crawl to discover and walk a site, readfetch_scrape when JavaScript is required. Read-only; 402 without PAYMENT-SIGNATURE like other paid tools.

Inputs: urls (required), format, pipeline, timeout_s, +1 more. Returns: credit, failed, status, results, +2 more

readfetch_crawlA
Read-only
Inspect

Paid routes require a funded Base USDC wallet. Use readfetch-client / @readfetch/client or the MCP signing proxy (@readfetch/mcp-x402-proxy). Direct calls without a signing client will stop at 402. Start a bounded async crawl from one seed URL. Returns job_id, status (queued), pages_quoted, and price_usd — then poll readfetch_crawl_status with that id until status is complete or failed. A complete job includes per-page url and Markdown in the status payload. Cap scope with max_pages (default 20, max 100) and max_depth (default 2, max 3); include/exclude filter paths by prefix (* suffix on include). Prefer readfetch_batch for a fixed URL list; readfetch_map to list URLs without fetching bodies; readfetch_text for a single page.

Inputs: url (required), exclude, include, max_depth, +1 more. Returns: hint, job_id, status, price_usd, +1 more

readfetch_crawl_statusA
Read-only
Inspect

FREE — no payment or wallet: Poll a crawl job started with readfetch_crawl. FREE — no payment or wallet; unauthenticated. Pass id from the crawl response. Returns job_id, status (queued, running, complete, or failed), completed/total counts, and a growing pages list (url plus Markdown) as results land. Stop polling when status is complete or failed. Results are kept for one hour after the job finishes.

Inputs: id (required). Returns: pages, total, job_id, status, +1 more

readfetch_diffA
Read-only
Inspect

Paid routes require a funded Base USDC wallet. Use readfetch-client / @readfetch/client or the MCP signing proxy (@readfetch/mcp-x402-proxy). Direct calls without a signing client will stop at 402. Stateless change detection on readable page text (same HTTP-first extraction as readfetch_text): fetch the URL, compare to a hash or prior body you store client-side, return changed/unchanged plus optional line diff. First call with no prior fields returns a baseline hash (see hint). previous_hash alone detects change without a line diff; add previous_content when you need added/removed/diff. A no-change answer is still billable when text was delivered. Prefer readfetch_text when you need the full article once; readfetch_probe (free) for a short preview and content_sha256 before spending on text.

Inputs: url (required), format, timeout_s, previous_hash, +1 more. Returns: url, diff, hash, hint, +6 more

readfetch_feedbackAInspect

FREE — report integration, docs or site issues for a prior call. Bind with request_id from X-Request-Id. Paid delivery disputes use /v1/claims, not this tool.

Inputs: message (required), category (required), request_id (required).

readfetch_fetchA
Read-only
Inspect

Paid routes require a funded Base USDC wallet. Use readfetch-client / @readfetch/client or the MCP signing proxy (@readfetch/mcp-x402-proxy). Direct calls without a signing client will stop at 402. Send an HTTP request (GET, POST, PUT, PATCH, DELETE, HEAD) through egress and return status_code, response headers, and body as text or base64 (binary: true). max_bytes caps the stored body; follow_redirects (default true) and timeout_s (95 s ceiling) apply to the full redirect chain. Use json_body for JSON POST/PUT payloads; use body for raw bytes or strings. Prefer readfetch_text for readable HTML articles; readfetch_pdf to extract PDF text (not raw bytes alone). POST/PUT/DELETE can change remote state despite readOnlyHint.

Inputs: url (required), body, binary, method, +5 more. Returns: url, size, text, billed, +3 more

readfetch_mapA
Read-only
Inspect

Paid routes require a funded Base USDC wallet. Use readfetch-client / @readfetch/client or the MCP signing proxy (@readfetch/mcp-x402-proxy). Direct calls without a signing client will stop at 402. Discover a site's crawlable surface without crawling it: parse robots.txt allow/disallow rules, collect URLs from sitemap.xml and sitemap indexes, find RSS, Atom and JSON feeds, and count internal and external links on the homepage. Use the returned URLs to plan readfetch_scrape, readfetch_batch, or readfetch_crawl — not readfetch_map again on each URL. Prefer readfetch_probe on one URL before paying for bodies.

Inputs: url (required), limit, max_bytes, timeout_s. Returns: url, host, urls, feeds, +8 more

readfetch_pdfA
Read-only
Inspect

Paid routes require a funded Base USDC wallet. Use readfetch-client / @readfetch/client or the MCP signing proxy (@readfetch/mcp-x402-proxy). Direct calls without a signing client will stop at 402. Extract text from a PDF (%PDF- magic, not Content-Type). Send exactly one of url (public http(s) link — egress GET, ≤ 20 MB) or content_base64 (bytes you already have — the whole request body is capped at 1 MiB, base64 expansion included; optional filename labels the upload). Returns pages (per-page text), one concatenated markdown body, title, and metadata; $0.005 per document, not per page. max_pages limits extraction (default 50, max 200); documents over 200 pages or above your cap return 413 and are not billed. Scanned/image-only PDFs may return empty text with billed: false and a hint. Prefer readfetch_text or readfetch_scrape for HTML articles; readfetch_fetch for raw PDF bytes without extraction; readfetch_batch for many HTML URLs, not PDFs. Read-only server-side; paid x402 like other routes.

Inputs: url, filename, max_pages, content_base64. Returns: hint, pages, title, billed, +6 more

readfetch_probeA
Read-only
Inspect

FREE — no payment or wallet: Free preflight on a URL before any paid readfetch_* call: HTTP status, content type, byte size, title, language, and whether a bot wall is waiting (challenge). When the response is HTML and not a challenge page, the JSON includes preview: the text readfetch_text would return (same extractor), up to 32,000 characters for the first 3 probes per IP per day, then 400 characters. Use readfetch_probe instead of readfetch_text when choosing a route or estimating size; if challenge: true, use readfetch_scrape (then readfetch_residential if still blocked), not readfetch_text. Plain HTTP only — no browser render.

Inputs: url (required), timeout_s, accept_language. Returns: url, bytes, title, billed, +9 more

readfetch_residentialA
Read-only
Inspect

Paid routes require a funded Base USDC wallet. Use readfetch-client / @readfetch/client or the MCP signing proxy (@readfetch/mcp-x402-proxy). Direct calls without a signing client will stop at 402. Identical request and response to /v1/scrape, but the render leaves through a residential address instead of the datacentre. For targets that block by IP reputation (DataDome, PerimeterX, Cloudflare, AWS WAF). One attempt, no retries: residential bandwidth is the cost, and four times the scrape price is what it takes to cover it honestly. Prefer readfetch_scrape when datacentre egress works; use readfetch_residential only after readfetch_scrape fails or readfetch_probe reports a persistent challenge.

Inputs: url (required), auth, mode, format, +2 more. Returns: url, title, billed, status, +2 more

readfetch_scrapeA
Read-only
Inspect

Paid routes require a funded Base USDC wallet. Use readfetch-client / @readfetch/client or the MCP signing proxy (@readfetch/mcp-x402-proxy). Direct calls without a signing client will stop at 402. Load a public URL in headless Chromium and return Markdown, plain text, or HTML (format, plus status_code, title, billed; optional links via advanced.include_links). mode sets latency and depth: fast (15 s, minimal render), render (30 s, default, full JS), full (60 s, scroll the page). Put scroll, wait_for, js_code, headers, cookies, and auth in advanced (options is deprecated, same shape). Prefer readfetch_text when JavaScript is not required; readfetch_fetch for raw HTTP/API bytes; readfetch_residential when the site blocks datacentre IPs; readfetch_screenshot for a PNG/JPEG. Bot-check or empty extractions may return billed: false with a hint.

Inputs: url (required), auth, mode, format, +2 more. Returns: url, title, billed, status, +2 more

readfetch_screenshotA
Read-only
Inspect

Paid routes require a funded Base USDC wallet. Use readfetch-client / @readfetch/client or the MCP signing proxy (@readfetch/mcp-x402-proxy). Direct calls without a signing client will stop at 402. Screenshot a public URL in headless Chromium (page JavaScript runs; no ad blocker) and return PNG or JPEG in JSON — image_base64, mime, width, height, status_code, billed (not a hosted URL). Scope: viewport only (full_page: false), full scrollable page (default), or one element (selector). mode caps total render time: fast (15 s), render (30 s, default), full (60 s, always full-page regardless of full_page). Set width/height before navigation (default 1280×800, max 3840×2160). delay_ms (0–30000) waits after navigation, then captures — raise it or use mode=full for slow SPAs and lazy media. Prefer readfetch_text or readfetch_scrape for extractable text; readfetch_pdf for PDF files; readfetch_fetch for raw HTTP without rendering. Read-only on the origin (GET + render, no form POST). Bot-check or blank frames may still return pixels with billed: false and a hint; paid x402 like other routes.

Inputs: url (required), mode, width, format, +4 more. Returns: url, hint, mime, size, +8 more

readfetch_sectionA
Read-only
Inspect

Paid routes require a funded Base USDC wallet. Use readfetch-client / @readfetch/client or the MCP signing proxy (@readfetch/mcp-x402-proxy). Direct calls without a signing client will stop at 402. Extract one heading or one CSS selector from a public page instead of the whole document. Returns matched Markdown or text, title, chars, content_sha256, and billed. If the heading is missing, returns HTTP 200 with empty text and available_headings so you can retry. mode: fast (plain HTTP) or render (default, Chromium when the page blocks HTTP). max_chars truncates output (default 8000, max 20000). Prefer readfetch_text for full articles; readfetch_scrape when content needs JavaScript.

Inputs: url (required), mode, format, heading, +2 more. Returns: url, hint, text, chars, +8 more

readfetch_textA
Read-only
Inspect

Paid routes require a funded Base USDC wallet. Use readfetch-client / @readfetch/client or the MCP signing proxy (@readfetch/mcp-x402-proxy). Direct calls without a signing client will stop at 402. Fetch a public URL and return its main readable content as Markdown or plain text, plus title, author, published date and site name. Strips navigation, ads and boilerplate. No JavaScript rendering by default (cheaper than readfetch_scrape); one Chromium fallback when plain HTTP is blocked. Prefer readfetch_fetch when you need raw status, headers, or non-HTML bytes; readfetch_scrape when the article only appears after JavaScript runs.

Inputs: url (required), format, max_bytes, timeout_s, +1 more. Returns: url, size, text, title, +7 more

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.3/5.0

    Scored across 15 tools

    Disambiguation4/5

    Many tools perform related extraction work (text, scrape, residential, fetch, batch), but each description explicitly states when to prefer it and points to alternatives. The main residual ambiguity is scrape vs residential, which have nearly identical request/response shapes differentiated only by egress.

    Naming Consistency5/5

    All tools use a consistent readfetch_ snake_case prefix with descriptive suffixes, and no mixed casing or verb-style conventions appear. The suffixes mix nouns and actions, but the overall pattern is predictable and readable.

    Tool Count4/5

    15 tools is at the upper end but appropriate for a broad web-acquisition suite covering text, scraping, PDFs, screenshots, search, crawling, and raw HTTP. Each route has a distinct role, though the surface is dense.

    Completeness4/5

    Coverage is broad: single-URL extraction, JS rendering, raw HTTP, PDFs, screenshots, batch reads, search, site mapping, async crawl with status polling, diffing, section extraction, probing, and feedback. Minor gaps include no crawl cancellation or structured/table extraction mode, but core workflows are covered.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers