[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10},"actionData","errors","root",{"_115":116},"routes/modules.$creator.$moduleId",{"_14":15,"_16":17,"_18":19,"_20":21},"routes/modules.$creator.$moduleId.endpoints",{"_11":12,"_13":-5},"error","Module not found","tools","module",{"_20":22,"_23":21,"_24":25,"_26":27,"_28":29,"_30":31,"_32":25,"_33":-5,"_34":35,"_36":-5,"_37":-5,"_38":39,"_40":41,"_42":43,"_44":45,"_46":45,"_47":48,"_49":50,"_51":52,"_53":-5,"_54":45,"_55":56,"_57":58,"_59":60,"_61":62,"_63":64,"_65":45,"_66":67,"_68":69,"_70":71,"_72":73,"_74":75,"_76":-5,"_77":-5,"_78":-5,"_79":45,"_80":-5,"_81":82,"_83":84,"_85":86,"_87":88,"_89":90,"_91":92,"_93":94},"apiUrl","https://odel.app/api","creator","fouradata","moduleId","mcp","@fouradata/mcp","displayName","tagline","Web scraping for AI agents: fetch any page via proxy or full browser, past anti-bot defenses.","iconKey","https://avatars.githubusercontent.com/u/298563228?v=4","category","data","status","published","metaDescription","metaKeywords","deploymentType","external","workerName","bindingName","mcpConfig","{\"url\":\"https://mcp.foura.ai/mcp\",\"transport\":\"streamable-http\",\"authType\":\"none\"}","pricingModel","free","creatorUserId","system:external-import","createdAt",1783311580000,"updatedAt","sourceRegistry","official-mcp-registry","sourceUrl","https://registry.modelcontextprotocol.io/v0/servers?search=ai.foura%2Fmcp","sourceVerified",false,"sourceMissingSince","importedAt","upstreamStars",2,"upstreamUpdatedAt",1782994861000,"detectedTransport","streamable-http","detectedAuthType","none","probeStatus","ok","lastProbedAt","githubRepoUrl","https://github.com/fouradata/mcp","githubRepoFullName","fouradata/mcp","releaseId","ext-fouradata-mcp","version","0.4.8","descriptionMarkdown","\n# @fouradata/mcp\n\n[![npm version](https://img.shields.io/npm/v/@fouradata/mcp?logo=npm&color=cb3837)](https://www.npmjs.com/package/@fouradata/mcp)\n[![npm downloads](https://img.shields.io/npm/dm/@fouradata/mcp?color=cb3837)](https://www.npmjs.com/package/@fouradata/mcp)\n[![provenance signed](https://img.shields.io/badge/supply_chain-provenance_signed-2ea44f?logo=npm)](https://www.npmjs.com/package/@fouradata/mcp)\n[![license MIT](https://img.shields.io/npm/l/@fouradata/mcp?color=2ea44f)](./LICENSE)\n[![smithery badge](https://smithery.ai/badge/foura/mcp)](https://smithery.ai/servers/foura/mcp)\n\n[FourA Web Scraping API](https://foura.ai/) as four [Model Context Protocol](https://modelcontextprotocol.io) tools plus six built-in workflow prompts. Plug it into Claude Desktop, Claude Code, Cursor, Windsurf, or any other MCP client and fetch arbitrary public web pages, bypass anti-bot challenges, and render JavaScript-heavy sites - without writing a line of integration code.\n\nFour tools, six prompts, one API key. One smart `foura_auto` tool picks the fetch method for you (direct, proxy, or full browser); drop to the primitives when you want explicit control. Published to npm with build [provenance](https://docs.npmjs.com/generating-provenance-statements) - the tarball is cryptographically traceable to this repo and CI run.\n\n**One-click install:**\n\n[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](cursor://anysphere.cursor-deeplink/mcp/install?name=foura&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBmb3VyYWRhdGEvbWNwIl0sImVudiI6eyJGT1VSQV9BUElfS0VZIjoiWU9VUl9GT1VSQV9BUElfS0VZIn19)\n[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522foura%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522-y%2522%252C%2522%2540fouradata%252Fmcp%2522%255D%252C%2522env%2522%253A%257B%2522FOURA_API_KEY%2522%253A%2522YOUR_FOURA_API_KEY%2522%257D%257D)\n\nBoth buttons pre-fill the config with a `YOUR_FOURA_API_KEY` placeholder - replace it with your key. Or by hand: `claude mcp add foura -- npx -y @fouradata/mcp` (set `FOURA_API_KEY` in env first). Full per-client setup below.\n\n[FourA](https://foura.ai) - [MCP page](https://foura.ai/mcp) - [GitHub](https://github.com/fouradata/mcp) - [npm](https://www.npmjs.com/package/@fouradata/mcp) - [Docs](https://foura.ai/docs/mcp/server) - [Hosted endpoint](https://mcp.foura.ai/mcp)\n\n## Quick Start - local stdio (recommended for Claude Desktop)\n\nGrab a key at [foura.ai/dashboard/#api-keys](https://foura.ai/dashboard/#api-keys) (one click, shown once on creation, format `pk_live_...`). Then drop this into your MCP client's config:\n\n```json\n{\n \"mcpServers\": {\n \"foura\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@fouradata/mcp\"],\n \"env\": {\n \"FOURA_API_KEY\": \"pk_live_...\"\n }\n }\n }\n}\n```\n\n> **Claude Desktop gotcha:** fully quit Claude Desktop (`Cmd+Q` on macOS) **before** editing the config file. If the app is still running, it will overwrite your edits with its in-memory config on exit.\n\nThe npx command downloads the package on first launch (~10s) and runs it as a subprocess of your MCP client. No global install needed. Same JSON works in every major client - just point it at the right file:\n\n| Client | Where the config lives |\n|---|---|\n| Claude Desktop (macOS) | `~/Library/Application Support/Claude/claude_desktop_config.json` |\n| Claude Desktop (Windows) | `%APPDATA%\\Claude\\claude_desktop_config.json` |\n| Claude Code | `claude mcp add foura -- npx -y @fouradata/mcp` (set `FOURA_API_KEY` in env first) |\n| Cursor | `~/.cursor/mcp.json` |\n| Windsurf | `~/.codeium/windsurf/mcp_config.json` |\n| VS Code (MCP extension) | `.vscode/mcp.json` in your workspace |\n\nRestart the client and `foura_auto`, `foura_single`, `foura_proxy`, `foura_browser` show up in your tool list, plus six prompts under `/prompts`.\n\n## Quick Start - hosted (Streamable HTTP)\n\nFor clients that support the Streamable HTTP transport (Cursor, Windsurf, VS Code, Claude Code with `--transport http`), point them at the hosted endpoint instead of running a local subprocess:\n\n```json\n{\n \"mcpServers\": {\n \"foura\": {\n \"url\": \"https://mcp.foura.ai/mcp\",\n \"headers\": {\n \"Authorization\": \"Bearer pk_live_...\"\n }\n }\n }\n}\n```\n\nCurrent Claude Desktop builds reject the bare `url` form - use the stdio config above for Claude Desktop, or bridge through `mcp-remote`:\n\n```json\n{\n \"mcpServers\": {\n \"foura\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"mcp-remote\", \"https://mcp.foura.ai/mcp\", \"--header\", \"Authorization: Bearer pk_live_...\"]\n }\n }\n}\n```\n\n## The Tools\n\n`foura_auto` is the **default** - give it a URL and it returns the content, picking the fetch method for you. The other three are the lower-level primitives it orchestrates; reach for them when you want explicit control.\n\nAll four are marked `readOnlyHint: true` and `openWorldHint: true` per the [MCP spec](https://modelcontextprotocol.io/specification/2025-06-18/server/tools) - clients that auto-approve trusted read-only tools (Claude Desktop, Cursor in 2026) call them without a per-request confirmation modal.\n\nEvery response carries both human-readable text (`content`) and a typed `structuredContent` JSON object validated against the tool's `outputSchema`. Clients pass `structuredContent` to your LLM natively, skipping the re-tokenization tax on stringified JSON.\n\n### `foura_auto` - smart fetch (the default)\n\nGive a URL, get the content back. Use this first when you just want the page and don't want to choose a method. Internally it walks a cost-aware ladder - a fast direct request, then a rotating proxy, then a full browser session - escalating only as far as the target forces it, solving common bot challenges on the way, and cheaply replaying a warm session on repeat calls to the same host. It learns the right settings per host, so there are no `maxTries` / pool / retry knobs to tune.\n\n```jsonc\n{\n \"url\": \"https://example.com\",\n // optional: a substring the REAL page must contain, so auto can tell a\n // real page from a challenge page on protected targets\n \"validate\": { \"data\": { \"accept\": [\"Example Domain\"] } }\n}\n```\n\nThe client surface is intentionally minimal: `url` (required), plus optional `method`, `headers`, `data`, `validate`, `returnSession` (default `true`), `forceProxy` (default `true`), `timeout_ms` (5000-180000, default 120000), `ignoreProxies`.\n\n`structuredContent` shape: `{status, headers, data, meta, session}`. `meta` is always present - `{rung, solved, attempts, credits}` - the trace of which rung delivered and what it cost. `session` (`{proxy, cookies, userAgent}`) is returned by default so you can replay the same session through `foura_single` / `foura_proxy` afterwards (pass `session.proxy` into their `proxy` field). Send `returnSession: false` to omit it. There is no `total_time` field on auto.\n\n### `foura_single` - fast HTTP\n\nOne HTTP request, response back. Typically 200ms-2s. Use it for static pages, JSON APIs, server-rendered HTML - the bread and butter of scraping. Set `unblocker: true` if the target is picky about wire-level signals.\n\n```jsonc\n{\n \"method\": \"GET\",\n \"url\": \"https://example.com\",\n \"unblocker\": true\n}\n```\n\nSupports custom headers, a body, per-stage timeouts, redirect controls, JSON auto-parse, a binary-buffer mode, and built-in response validation (`validate.status.accept`, `validate.data.fail`, and so on). If `foura_single` comes back blocked - status 403/429, captcha page, OR response headers `x-vercel-mitigated: challenge` / `cf-mitigated: challenge`, OR body title matches `Vercel Security Checkpoint` / `Just a moment` / `Attention Required` - escalate to `foura_proxy` with `maxTries: 25-30` for these tier-1 WAFs. If the page also needs JavaScript to render, chain `foura_proxy`'s returned `proxy` ID into `foura_browser.proxy`.\n\n`structuredContent` shape: `{status, headers, data, total_time, ...}`.\n\n### `foura_proxy` - rotating proxies with retry\n\nSame target shape as `foura_single`, but routed through a pool of proxies with automatic retry on failure. Per-host scoring picks the proxies most likely to succeed against this particular target, so you're not burning attempts on known-bad routes.\n\n```jsonc\n{\n \"maxTries\": 5,\n \"request\": {\n \"method\": \"GET\",\n \"url\": \"https://example.com/pricing\",\n \"unblocker\": true\n }\n}\n```\n\nTypical latency 1-5s. `structuredContent` adds `proxy` (the encoded ID of the proxy that succeeded - pass it to `ignoreProxies` next time if it later goes bad) and `total` (outer timing including selection + retries). For tier-1 WAF challenges (Vercel Security Checkpoint, Cloudflare 'Just a moment', Akamai Bot Manager) use `maxTries: 25-30` - the default 5 is sized for lightly-blocked sites. If still blocked after 30 attempts the gate is likely country / ASN allowlist (not solvable by rotation) - pivot strategy. If the target needs JavaScript render, chain the returned `proxy` ID into `foura_browser.proxy` - the browser then exits through the IP that already cleared the challenge for this target.\n\n### `foura_browser` - full browser session\n\nA real browser session. JavaScript runs, the DOM finishes rendering, cookies come back with the response. Use it when the page is a single-page app, when content lazy-loads after first paint, or when there's an anti-bot challenge that needs a real browser to clear.\n\n```jsonc\n{\n \"url\": \"https://example.com/spa\",\n \"timeout_ms\": 15000,\n \"checkText\": \"data-table\"\n}\n```\n\nSlowest of the lower-level tools (2-10s) but the only tool that handles JavaScript end-to-end. `checkText` is a one-shot post-render validator (substring search on the rendered HTML AFTER navigation completes - not a waiter, does not poll): if the substring is missing, the call fails with an error envelope. Useful when a page returns 200 but the actual content is missing. `unblocker` defaults to `true` - the session actively solves an anti-bot / captcha challenge (Cloudflare Turnstile and similar) it meets along the way; set `unblocker: false` to render and return the page exactly as it loads, challenge page included.\n\n`structuredContent` shape is intentionally different from single/proxy: `{status, headers (object, not array), body (not data), cookies (full browser cookie shape), userAgent}`.\n\n## Built-in Prompts\n\nSix workflow templates surfaced under `/prompts` in your MCP client. They orchestrate one or more tools without you spelling out the steps.\n\n| Prompt | Arguments | What it does |\n|---|---|---|\n| `smart_fetch` | `url, must_contain?, extract?` | Auto fetch (picks the method, handles bot protection) → return or extract content |\n| `scrape_product_page` | `url` | Browser fetch → extract title, price, image, stock, SKU as JSON |\n| `extract_article` | `url` | Single → fallback to proxy → strip nav/ads → return clean article JSON |\n| `monitor_pricing` | `url, target_price?` | Proxy fetch → extract price → compare to target |\n| `check_endpoint_health` | `url, expected_text?` | Single with strict validation → reachable/status/timing report |\n| `bulk_fetch_urls` | `urls` (comma-separated) | Parallel single → auto-fallback to proxy per URL → metadata only |\n\nEach prompt arrives as a templated user message your LLM executes with the right tools. They cost zero tokens at idle - only invoked prompts enter the context window.\n\nFull recipe text + manual fallback prompts: [foura.ai/docs/mcp/recipes](https://foura.ai/docs/mcp/recipes). For the full error code list, see [foura.ai/docs/mcp/errors](https://foura.ai/docs/mcp/errors).\n\n## Authentication\n\nYour `Bearer` token (or the `FOURA_API_KEY` env var in stdio mode) forwards to the FourA API as `X-API-Key`. One key, all four tools.\n\nKeys are managed in the [dashboard](https://foura.ai/dashboard/#api-keys) - shown once on creation, rotate or deactivate any time. See [foura.ai/docs/getting-started/authentication](https://foura.ai/docs/getting-started/authentication) for the full key-management walkthrough.\n\n## Error envelope - typed contract for agent retries\n\nEvery error (`isError: true`) carries a `structuredContent` envelope with at minimum these three fields:\n\n```jsonc\n{\n \"service\": \"single\" | \"proxy\" | \"browser\",\n \"code\": \"ssrf_blocked\" | \"auth_failed\" | \"rate_limited\" | ...,\n \"error\": \"Human-readable message\"\n}\n```\n\nWhere the upstream returned a status, you also get `status` (HTTP code) and on rate-limit / capacity errors the FourA API envelope adds `retryAfter`, `current.{concurrency, rpm}`, `limits.{maxConcurrency, maxRpm}`.\n\n| `code` | When | Retry safe? |\n|---|---|---|\n| `ssrf_blocked` | Target IP in a private / reserved range (RFC 5735+6598+IPv6 reserved) | No - change the URL |\n| `upstream_non_json` | Upstream returned malformed body | Maybe - investigate |\n| `bad_request` (400) | Input shape rejected by FourA | No - fix arguments |\n| `auth_failed` (401) | Key missing, invalid, or deactivated | No - fix the key |\n| `forbidden` (403) | Authenticated but not allowed | No |\n| `not_found` (404) | Target / endpoint doesn't exist | No |\n| `rate_limited` (429) | RPM cap hit | Yes - wait `retryAfter` |\n| `at_capacity` (503) | Concurrency cap hit | Yes - wait `retryAfter` |\n| `service_disabled` (503) | Maintenance window | Yes - wait `retryAfter` |\n| `service_unavailable` (503) | Generic 503 | Yes - short backoff |\n| `upstream_error` (≥500) | Upstream 5xx | Yes - exponential backoff |\n| `upstream_client_error` (4xx) | Other 4xx | Usually no |\n\nLLM agents can read `code` directly for retry logic without parsing prose. Spec reference: [foura.ai/docs/api/errors](https://foura.ai/docs/api/errors).\n\n## Combining the tools - sticky exit IPs\n\nThe lower-level tools compose. `foura_proxy` returns the base36 ID of the exit it used. Pass that ID back into `foura_single.proxy` or `foura_browser.proxy` and the next call exits through the **same IP** - same session, same fingerprint, same geo.\n\n```jsonc\n// 1. Find a working exit for the target - use maxTries:25-30 for tier-1 WAFs\nconst r = await foura_proxy({\n maxTries: 30,\n request: { method: \"GET\", url: \"https://probe.example.com\", unblocker: true }\n});\n// → { status: 200, proxy: \"4DZ3VE\", ... }\n\n// 2. Reuse it for follow-up HTTP (cookies, multi-step flows)\nawait foura_single({ method: \"GET\", url: \"https://target/api\", proxy: r.proxy });\n\n// 3. Or render JS through the same egress - exits through the IP that already\n// cleared the challenge for this target, so the snapshot captures the real\n// post-challenge content instead of a challenge page.\nawait foura_browser({ url: \"https://target/spa\", proxy: r.proxy });\n```\n\nThis chain is the canonical pattern for **tier-1 WAF + JavaScript-rendered targets** (Vercel Security Checkpoint, Cloudflare 'Just a moment', Akamai Bot Manager protecting SPAs). Calling `foura_browser` directly against a WAF target usually captures the challenge page - the snapshot fires before the challenge's deferred reload completes. Solve via `foura_proxy` first, then chain.\n\nTo rotate AWAY from a known-bad proxy on the next `foura_proxy` call, pass it as `ignoreProxies: [\"4DZ3VE\"]`. The `proxy` field on `foura_single` and `foura_browser` also accepts raw URLs (`http://host:port`, `socks5://...`) if you have your own list.\n\n## Large responses - `offload_large` (default: inline)\n\nBy default (since v0.2.0), full response bodies are returned inline in `structuredContent` regardless of size. This works in every MCP client.\n\nIf your client supports MCP `resources/read` (and you want to save tokens on big pages), pass `offload_large: true` per tool call. Responses ≥ 50 KB are then written to disk, returned as a `resource_link`, and your client fetches the body only when it actually needs it. Cached payloads expire after 1 hour.\n\n```jsonc\n{\n \"method\": \"GET\",\n \"url\": \"https://en.wikipedia.org/wiki/Web_scraping\",\n \"offload_large\": true // opt in for token savings\n}\n```\n\n| Client | `offload_large: true` |\n|---|---|\n| Claude Desktop | not yet - leave default `false` |\n| Claude Code, Cursor, Windsurf | supported |\n| VS Code MCP extension | supported |\n\nTenant-isolated: only the API key that stored a payload can read it back.\n\n## Other limits\n\n- **Private targets are refused.** Requests to private or reserved IP ranges (RFC 5735, 6598, IPv6 reserved blocks) are blocked at the MCP layer. Only public-internet hosts are forwarded.\n- **Rate limits** are enforced by the FourA API per service. Concurrency + RPM. Details at [foura.ai/docs/api/rate-limits](https://foura.ai/docs/api/rate-limits).\n- **Body size cap** of 256 KB on incoming `/mcp` requests (real MCP payloads are < 4 KB).\n- **DNS-rebinding defense:** the hosted server validates `Origin` and `Host` headers. Browser-based callers must originate from an allowlisted origin. Server-to-server callers (curl, MCP clients in stdio bridge mode) are unaffected.\n\n## Self-Hosting\n\nThe MCP server runs in one container, statelessly - each request brings its own key, so there's no session state, no sticky load balancing, nothing to coordinate. Scale horizontally behind any load balancer.\n\nConfigurable environment:\n\n| Variable | Default | Purpose |\n|---|---|---|\n| `PORT` | `3076` | HTTP listen port |\n| `FOURA_API_BASE` | `https://api.foura.ai/api` | Upstream FourA REST base URL |\n| `FOURA_MCP_PAYLOADS_DIR` | `/data/payloads` | Where ≥50 KB responses are cached on disk |\n\nThe full source is public here under MIT - build the container from the included [`Dockerfile`](https://github.com/fouradata/mcp/blob/main/Dockerfile) (`docker build -t foura-mcp .`), or run it straight from npm with `npx -y @fouradata/mcp`. See [DEVELOPMENT.md](https://github.com/fouradata/mcp/blob/main/DEVELOPMENT.md) for the local build and test workflow.\n\n## License\n\nMIT. See [`LICENSE`](https://github.com/fouradata/mcp/blob/main/LICENSE).\n\n## Links\n\n- FourA (web scraping API): \n- MCP server page: \n- Source (GitHub): \n- npm package: \n- API documentation: \n- MCP server reference: \n- MCP error codes: \n- MCP recipes: \n- REST API errors: \n- MCP specification: \n- Get a key: \n","changelogMarkdown","videoKey","requiredSecretsJson","publishedAt","priceCents","trialDays",0,"categoryDisplayName","Data & Analytics","upstream",{"_97":98,"_99":100,"_101":102,"_103":104,"_105":106},"requiredSecrets",[],"tags",[],"assets",[],"stats",{"_95":82,"_96":82},"ratingAvg","reviewCount","topics",[107,108,109,110,21,111,112,113,114],"license","MIT","language","JavaScript","registryName","ai.foura/mcp","homepage","https://foura.ai/mcp","ai-agents","claude","cursor","llm-tools","mcp-server","model-context-protocol","typescript","web-scraping","ENV",{"_117":118,"_119":120,"_121":122},"ENVIRONMENT","production","TURNSTILE_SITE_KEY","0x4AAAAAAB8-rEI2gNDf_QhU","SENTRY_DSN","https://45fd1229f78089d5c3ee78be128030e1@o4510583261757440.ingest.de.sentry.io/4510584253448272"]