The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the CleanPage listing page.
A paid MCP tool that turns any URL into clean, structured, agent-optimized content. Agents pay $0.02 USDC per successful call via x402 on Base — no accounts, no API keys, no subscriptions.
Built for Cloudflare Workers. Full TypeScript. No paid infra required beyond a domain and a Base wallet address.
Discover the service for free — no payment needed for any of this:
GET /.well-known/agent.json — machine-readable capability cardGET /.well-known/mcp.json — MCP connection + pricing manifestGET /llms.txt — plain-text summary for LLM crawlershealth, list_capabilities, pricing (all free)Connect an MCP client to https://<your-domain>/mcp over Streamable HTTP:
Call clean_page with no payment attached first:
The response is HTTP 402 with an accepts array describing exactly what payment is required (amount, network, asset, payee address).
Sign and retry. Construct a USDC transferWithAuthorization (EIP-3009) payment payload for the requested amount, base64-encode it, and retry the same request with an X-PAYMENT header. Most x402 client libraries (e.g. x402-fetch, x402-axios) do steps 3–4 for you automatically.
Get the result. On success, the response carries the full JSON result plus an X-PAYMENT-RESPONSE header with the settlement transaction hash. Failed extractions (paywalls, bot-blocks, empty pages) are never charged — settlement only happens after a successful extraction.
Full protocol details: see /llms.txt and /.well-known/mcp.json once deployed, or the "For agents" section of the landing page.
MCP transport. The MCP Streamable HTTP transport is implemented directly in src/mcp/server.ts as a stateless JSON-RPC 2.0 dispatcher (initialize, tools/list, tools/call, ping), rather than via the official SDK's Node-oriented HTTP transport class. This is a deliberate choice for correctness on Cloudflare Workers: the SDK's transport targets Node's http.IncomingMessage/ServerResponse, which Workers doesn't have. The dispatcher here follows the same wire protocol (JSON-RPC over a single POST endpoint, one server-scoped session per request) so any standard MCP client can connect to it. If you later run this on a Node-based host, you can swap in @modelcontextprotocol/sdk's StreamableHTTPServerTransport directly.
Payment gating. POST /mcp peeks at the parsed JSON-RPC body: only tools/call requests naming clean_page are payment-gated (src/index.ts); health, list_capabilities, pricing, and all non-tool-call methods (initialize, tools/list, etc.) pass straight through, rate-limited but free. This keeps the discovery surface fully open to agents while gating only the one paid capability.
Settlement timing. Payment is verified before extraction runs, but settled (broadcast on-chain) only after extraction succeeds. If extraction fails, the agent's payment authorization is simply discarded — nothing is charged.
No private key required. Because USDC on Base supports EIP-3009 meta-transactions, the resource server never holds a private key. PAYMENT_ADDRESS is a public wallet address; the facilitator submits the signed authorization on-chain and sponsors gas.
Extraction engine. @mozilla/readability (the engine behind Firefox Reader Mode) does the core content extraction, running against a DOM built with linkedom (a fast, dependency-light DOM implementation that works in Workers — jsdom does not). A small hand-written HTML→Markdown walker converts the extracted fragment to markdown, since no existing markdown-conversion library is both Workers-compatible and DOM-based. Heuristics before and after extraction catch common failure modes: paywall markers, bot-check pages, and JS-only empty shells all produce typed errors instead of low-quality output.
Optional LLM enrichment. structured_facts is populated only when the caller passes options.extract_facts: true, and only if ENABLE_LLM_ENRICHMENT=true and ANTHROPIC_API_KEY is set. It's off the critical path — if the enrichment call fails or is disabled, clean_page still returns a complete result with an empty structured_facts array and a note explaining why. There's no additional charge for using it.
Rate limiting & analytics. Both are implemented with a single KV namespace: a fixed 1-minute-window counter per client IP for free-tier calls, and a running JSON counter object for total calls / successes / failures / revenue, exposed read-only at GET /analytics.
| Component | What you need | Where to get it |
|---|---|---|
| Hosting | Cloudflare Workers (with Static Assets) | dash.cloudflare.com — free tier works to start |
| Domain + DNS | A domain proxied through Cloudflare | Any registrar; add to Cloudflare, point at the Worker |
| Wallet | A Base wallet address (public address only) | Any EVM wallet — Coinbase Wallet, MetaMask, etc. |
| x402 facilitator | Verifies/settles payments | https://x402.org/facilitator (testnet-friendly default); Coinbase-operated or self-hosted facilitators for mainnet production volume |
| KV namespace | Rate limiting + analytics storage | wrangler kv namespace create CLEANPAGE_KV |
| LLM (optional) | Structured fact extraction | Anthropic API key, only if ENABLE_LLM_ENRICHMENT=true |
No database, no queue, no separate backend — everything runs in the one Worker.
X402_NETWORK from base-sepolia to base in wrangler.toml.X402_FACILITATOR_URL to a mainnet-capable facilitator (confirm your chosen facilitator supports Base mainnet settlement — verify current facilitator options, as this ecosystem is still young and options change).See .env.example for the full annotated list. Summary:
| Variable | Required | Default | Purpose |
|---|---|---|---|
PAYMENT_ADDRESS | yes | — | Base wallet address receiving USDC |
X402_NETWORK | yes | base-sepolia | base or base-sepolia |
X402_FACILITATOR_URL | yes | https://x402.org/facilitator | Facilitator used for verify/settle |
CLEAN_PAGE_PRICE_USD | yes | 0.02 | Price per successful clean_page call |
PUBLIC_BASE_URL | yes | — | Your deployed URL, used in discovery files |
FREE_RATE_LIMIT_PER_MIN | no | 30 | Free-tier calls per IP per minute |
ENABLE_LLM_ENRICHMENT | no | true | Enables structured_facts extraction |
LLM_MODEL | no | claude-haiku-4-5-20251001 | Model used for enrichment |
ANTHROPIC_API_KEY | only if enrichment enabled | — | Secret; set via wrangler secret put |
Request:
Successful response (after payment) — result.content[0].text is a JSON string shaped like:
error_code | Meaning | Retryable |
|---|---|---|
INVALID_URL | Malformed, non-http(s), or a blocked internal address | no |
FETCH_FAILED | Non-2xx response, non-HTML content, or oversized page | sometimes |
TIMEOUT | Page didn't respond within the timeout | yes |
PAYWALL_DETECTED | Subscription/metered paywall detected | no |
BLOCKED_BY_SITE | Bot-check/CAPTCHA or JS-only empty shell | no |
EMPTY_CONTENT | No substantial article content found | no |
EXTRACTION_FAILED | Unexpected parser error | no |
Failed extractions always return before payment settlement, so they're never charged.
EMPTY_CONTENT or BLOCKED_BY_SITE. Adding a headless-browser rendering fallback (e.g. via Cloudflare Browser Rendering) is the natural next step if this matters for your traffic.x402.org/facilitator is a good default for development; evaluate production facilitators for reliability guarantees before scaling mainnet volume.