ai.foura/mcp

Official4 tools

by fouradata · JavaScript

Web scraping for AI agents: fetch any page via proxy or full browser, past anti-bot defenses.

Scrape web pages using proxies or full browser rendering to bypass protections.

Topics

claudemcpmodel-context-protocoltypescriptweb-scrapingai-agentscursorllm-toolsmcp-server

Captured live from the server via tools/list.

foura_single

Send one HTTP request and return the response. Fastest of the four tools (typically 200ms-2s). Use for static pages, JSON APIs, server-rendered HTML. Set unblocker:true if the target has wire-level anti-bot protection. Switch to foura_proxy if you get blocked - status 403, status 429, captcha page, OR response carries `x-vercel-mitigated: challenge` / `cf-mitigated: challenge` headers, OR body title matches `Vercel Security Checkpoint` / `Just a moment` / `Attention Required` / `We're verifying your browser`. For these tier-1 WAF challenges call foura_proxy with maxTries:25-30 (the default 5 is sized for lightly-blocked sites). On success, chain the returned proxy ID into foura_browser.proxy if the page also needs JavaScript to render.

Parameters (16)

methodstringrequired
HTTP method (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS, or any WebDAV verb like PROPFIND/MKCOL)
urlstringrequired
Target URL. Public hosts only - private/reserved ranges (RFC 1918 10/8, 172.16/12, 192.168/16, loopback 127/8, link-local, IPv6 ULA fc00::/7, IPv6 loopback ::1, plus *.local mDNS) are refused with code `ssrf_blocked`. Example: https://example.com/page or https://api.example.com/v1/users. Use {ts} anywhere in the URL to insert current Unix timestamp for cache-bust.
headersarray
Custom HTTP headers as [name, value] tuples. Example: [["Accept", "application/json"], ["Referer", "https://google.com/"]]
unblockerboolean
Inject realistic browser headers (User-Agent, Sec-Ch-Ua, Accept-Encoding, …) and make the request look like it's coming from a real browser at the wire level. Default false - set true for any target with anti-bot or WAF (Cloudflare, Akamai, PerimeterX, Datadome). Cheap to leave on for production scrapes.
dataany
Request body. Strings sent as-is; objects auto-serialized to JSON. Example: {"query": "hello"} for POST APIs.
proxystring
Optional proxy. Two forms: (1) URL `http://host:port` or `socks5://host:port`; (2) base36 ID from foura_proxy (e.g. `4DZ3VE`) - same exit IP. For rotation, use foura_proxy.
timeout_msinteger
Overall request timeout in ms (max 120000, default 15000)
connect_timeout_msinteger
Timeout in ms for establishing the TCP/TLS connection (0-120000). Omit to use the default.
accept_timeout_msinteger
Timeout in ms to receive the first response byte after the request is sent (0-120000). Omit for the default.
server_response_timeout_msinteger
Timeout in ms for the server to send the complete response (0-120000). Omit for the default.
dns_cache_timeout_secinteger
How long (seconds) to cache the target's resolved DNS (0-240). Omit for the default.
followRedirectsinteger
Max number of redirects to follow (0-20). Omit to disable redirect following.
tryJsonDataboolean
If true, attempt JSON.parse on the response body. On success, `data` is the parsed value (typically object or array). On parse failure, `data` silently stays as the original string - no error, no warning. Set false (or omit) when you need to detect parse failures explicitly.
returnBufferboolean
Return raw bytes as a serialized Buffer JSON shape (`{type:"Buffer", data:[byte, ...]}`, bytes 0-255) instead of decoded string. Use for binary responses (images, protobuf). Reconstruct: `Buffer.from(data.data)` in Node, `new Uint8Array(data.data)` elsewhere.
validateobject
Post-fetch response validation. When the response fails these checks the tool returns an error envelope.
offload_largeboolean
If true, response bodies >= 50KB are written to disk and returned as a resource_link instead of inlined. Saves token context but requires a client that supports `resources/read`. Default false.

foura_proxy

Route an HTTP request through FourA's proxy pool with automatic retry across multiple proxies. Per-host proxy rating picks proxies most likely to succeed for the target. Use when foura_single returns 403, captcha, or geo-blocked content. Typical latency 1-5s. The response includes the encoded proxy ID that succeeded ('proxy' field) - reuse it in foura_single.proxy or foura_browser.proxy to pin follow-up requests to the same exit IP, or pass it in ignoreProxies to skip this exit on the next rotation. Escalate to foura_browser if all proxies fail or the page needs JavaScript rendering. When the trigger is a tier-1 WAF challenge (Vercel Security Checkpoint, Cloudflare 'Just a moment', Akamai Bot Manager), set maxTries to 25-30 - the default 5 will usually be too low for these targets. Distinguish from country / ASN allowlist denials (country-licensed bookmakers, government sites): there rotation never helps regardless of maxTries - after ~30 failed attempts on the same block, stop climbing and pivot strategy instead.

Parameters (5)

requestobjectrequired
The inner HTTP request to send through each proxy attempt. Validation rules here determine when a proxy is treated as failed and retried.
maxTriesinteger
Maximum proxy rotation attempts before giving up (default 5, max 90). Default 5 is sized for lightly-blocked sites. Raise to 25-30 for tier-1 WAF challenges (Vercel Security Checkpoint, Cloudflare 'Just a moment', Akamai Bot Manager) - most rotations on these targets need this range. If still blocked after 30 attempts, the gate is likely country / ASN allowlist (not solvable by rotation) - pivot strategy instead of climbing to 60.
timeout_msinteger
Overall timeout across all rotation attempts in ms (default 45000, max 120000). Must be positive.
ignoreProxiesarray
Encoded proxy IDs (base36 strings like "4DZ3VE") OR proxy URLs to exclude from rotation. Both forms are accepted.
offload_largeboolean
If true, response bodies >= 50KB are written to disk and returned as a resource_link instead of inlined. Default false.

foura_browser

Load a URL in a real browser session. JS runs, DOM renders, cookies come back. 2-10s. Use for SPAs, lazy-loaded content, or JS anti-bot challenges (Cloudflare Turnstile etc.). Prefer foura_single for static HTML; foura_proxy for static pages where your IP is blocked. To rotate the browser's exit IP: call foura_proxy first, pass its returned `proxy` ID into this tool's `proxy` field - the browser exits through that pool IP. Default (no `proxy`) is one fixed container egress. If the target is behind a tier-1 WAF challenge (Vercel / Cloudflare / Akamai), calling this tool directly will usually still capture the challenge page rather than the post-challenge content - the snapshot fires before the challenge's deferred reload completes. Correct chain: call foura_proxy first with maxTries:25-30 against the same URL → take the returned proxy base36 ID → pass it into this tool's `proxy` field. The browser then exits through the IP that already cleared the challenge for this target. By default the browser actively solves an anti-bot / captcha challenge it meets along the way (the `unblocker` flag, default true); set `unblocker:false` to skip solving and return the page exactly as it loads, challenge page included.

Parameters (10)

urlstringrequired
Target URL to load in a full browser session. Public hosts only - private/reserved ranges (RFC 1918 + loopback + link-local + IPv6 ULA/loopback + *.local mDNS) are refused with code `ssrf_blocked`. Example: https://shop.example.com/product/123 or any single-page-app URL.
headersobject
Custom HTTP headers as a key-value object (NOT [name, value] tuples). Example: {"Referer": "https://google.com/"}
cookiesarray
Cookies to set before navigation: [{ name, value, domain? }]
userAgentstring
Override the browser's User-Agent string
proxystring
Optional proxy. Three forms: (1) URL `http://user:pass@host:port` or `socks5://host:port`; (2) base36 ID from foura_proxy (e.g. `4DZ3VE`) - same pool exit IP; (3) omit → fixed container egress.
timeout_msinteger
Page load timeout in ms (default 30000, max 120000)
checkStatusinteger
Expected HTTP status code. If the page returns a different status → tool returns an error envelope with the actual status carried in the envelope. Example: 200 for product pages, or 404 to assert a soft-404 didn't leak through.
checkTextstring
One-shot post-render validator - substring search on the rendered HTML AFTER navigation completes. NOT a waiter: does not poll, does not block until the substring appears. If the substring is missing, the tool returns an error envelope. Use to catch silent failures like a 200 response that captured a challenge page or empty SPA shell. Example: "add to cart" for product pages.
unblockerboolean
Actively SOLVE an anti-bot / captcha challenge (Cloudflare Turnstile and similar) encountered during navigation, instead of just rendering it. Default true. Set false to render and return the page exactly as it loads - including a challenge page - without attempting to solve; cheaper when you already know the target is open or you want the raw challenge page.
offload_largeboolean
If true, response bodies >= 50KB are written to disk and returned as a resource_link instead of inlined. Default false.

foura_auto

Give a URL, get the content back. The default first choice for any page when you just want the data and don't want to decide how to fetch it. Internally it walks a cost-aware ladder - a fast direct request first, then a rotating proxy, then a full browser session - escalating only as far as the target forces it, solving common bot challenges (Cloudflare, and similar) on the way, and cheaply replaying a warm session on repeat calls to the same host. It learns the right settings per host on its own, so there are no maxTries / pool / retry knobs to tune. Pass `validate` (a substring the real page must contain) on protected targets so it can tell a real page from a challenge page. The response includes a `meta` trace (which rung delivered, credits spent) and, by default, the winning `session` ({proxy, cookies, userAgent}) so you can replay it through foura_single / foura_proxy afterwards. Use one of the lower-level tools instead only when you need explicit control: foura_single for a specific raw HTTP request, foura_proxy to drive the rotation/exit yourself, foura_browser for a scripted browser session.

Parameters (11)

urlstringrequired
Target URL. Public hosts only - private/reserved ranges (RFC 1918 10/8, 172.16/12, 192.168/16, loopback 127/8, link-local, IPv6 ULA fc00::/7, IPv6 loopback ::1, plus *.local mDNS) are refused with code `ssrf_blocked`. Example: https://example.com/page. Use {ts} anywhere in the URL to insert the current Unix timestamp for cache-bust.
methodstring
HTTP method for the target request (default GET).
headersarray
Custom HTTP headers to send to the TARGET, as [name, value] tuples. Example: [["Accept", "application/json"], ["Authorization", "Bearer ..."]]
dataany
Request body for non-GET methods. Strings sent as-is; objects auto-serialized to JSON.
validateobject
Post-fetch response validation. When the response fails these checks foura_auto returns an error envelope.
returnSessionboolean
Return the {proxy, cookies, userAgent} session triple of the winning session so you can replay it through foura_single / foura_proxy later. Default true. Send false for a leaner response when you only need the content.
forceProxyboolean
Always reach the target through a rotating proxy, never from FourA's own egress. Default true (the target never sees FourA's origin IP). Send false to allow the cheaper direct path - but note some trust-gated defenses actually resolve more easily from the direct egress, so forcing a proxy can make those targets harder (more attempts / credits).
timeout_msinteger
Total time budget in ms for the WHOLE operation - auto fires several internal attempts and they must all fit inside this. Default 120000, max 180000. Auto portions the budget across its attempts; it does not hand the whole budget to one attempt.
ignoreProxiesarray
Exits to AVOID - base36 proxy ids (like "4DZ3VE") or proxy URLs. Auto skips a warm session on one of these and tells its internal proxy search to avoid them too. Use to rotate away from an exit that just got blocked.
followRedirectsinteger
Follow up to N redirects on the cheap (direct / proxy) rungs so a 301/302 lands on the real content instead of being returned as-is. Default 5; 0 = don't follow. The browser rung follows redirects natively.
offload_largeboolean
If true, response bodies >= 50KB are written to disk and returned as a resource_link instead of inlined. Saves token context but requires a client that supports `resources/read`. Default false.

README.md18 KBView on GitHub

@fouradata/mcp

FourA Web Scraping API as four Model Context Protocol 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.

Four 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 - the tarball is cryptographically traceable to this repo and CI run.

One-click install:

Both 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.

FourA - MCP page - GitHub - npm - Docs - Hosted endpoint

Quick Start - local stdio (recommended for Claude Desktop)

Grab a key at foura.ai/dashboard/#api-keys (one click, shown once on creation, format pk_live_...). Then drop this into your MCP client's config:

json

{
  "mcpServers": {
    "foura": {
      "command": "npx",
      "args": ["-y", "@fouradata/mcp"],
      "env": {
        "FOURA_API_KEY": "pk_live_..."
      }
    }
  }
}

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.

The 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:

Client	Where the config lives
Claude Desktop (macOS)	`~/Library/Application Support/Claude/claude_desktop_config.json`
Claude Desktop (Windows)	`%APPDATA%\Claude\claude_desktop_config.json`
Claude Code	`claude mcp add foura -- npx -y @fouradata/mcp` (set `FOURA_API_KEY` in env first)
Cursor	`~/.cursor/mcp.json`
Windsurf	`~/.codeium/windsurf/mcp_config.json`
VS Code (MCP extension)	`.vscode/mcp.json` in your workspace

Restart the client and foura_auto, foura_single, foura_proxy, foura_browser show up in your tool list, plus six prompts under /prompts.

Quick Start - hosted (Streamable HTTP)

For 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:

json

{
  "mcpServers": {
    "foura": {
      "url": "https://mcp.foura.ai/mcp",
      "headers": {
        "Authorization": "Bearer pk_live_..."
      }
    }
  }
}

Current Claude Desktop builds reject the bare url form - use the stdio config above for Claude Desktop, or bridge through mcp-remote:

json

{
  "mcpServers": {
    "foura": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.foura.ai/mcp", "--header", "Authorization: Bearer pk_live_..."]
    }
  }
}

The Tools

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.

All four are marked readOnlyHint: true and openWorldHint: true per the MCP spec - clients that auto-approve trusted read-only tools (Claude Desktop, Cursor in 2026) call them without a per-request confirmation modal.

Every 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.

`foura_auto` - smart fetch (the default)

Give 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.

jsonc

{
  "url": "https://example.com",
  // optional: a substring the REAL page must contain, so auto can tell a
  // real page from a challenge page on protected targets
  "validate": { "data": { "accept": ["Example Domain"] } }
}

The 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.

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.

`foura_single` - fast HTTP

One 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.

jsonc

{
  "method": "GET",
  "url": "https://example.com",
  "unblocker": true
}

Supports 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.

structuredContent shape: {status, headers, data, total_time, ...}.

`foura_proxy` - rotating proxies with retry

Same 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.

jsonc

{
  "maxTries": 5,
  "request": {
    "method": "GET",
    "url": "https://example.com/pricing",
    "unblocker": true
  }
}

Typical 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.

`foura_browser` - full browser session

A 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.

jsonc

{
  "url": "https://example.com/spa",
  "timeout_ms": 15000,
  "checkText": "data-table"
}

Slowest 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.

structuredContent shape is intentionally different from single/proxy: {status, headers (object, not array), body (not data), cookies (full browser cookie shape), userAgent}.

Built-in Prompts

Six workflow templates surfaced under /prompts in your MCP client. They orchestrate one or more tools without you spelling out the steps.

Prompt	Arguments	What it does
`smart_fetch`	`url, must_contain?, extract?`	Auto fetch (picks the method, handles bot protection) → return or extract content
`scrape_product_page`	`url`	Browser fetch → extract title, price, image, stock, SKU as JSON
`extract_article`	`url`	Single → fallback to proxy → strip nav/ads → return clean article JSON
`monitor_pricing`	`url, target_price?`	Proxy fetch → extract price → compare to target
`check_endpoint_health`	`url, expected_text?`	Single with strict validation → reachable/status/timing report
`bulk_fetch_urls`	`urls` (comma-separated)	Parallel single → auto-fallback to proxy per URL → metadata only

Each 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.

Full recipe text + manual fallback prompts: foura.ai/docs/mcp/recipes. For the full error code list, see foura.ai/docs/mcp/errors.

Authentication

Your 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.

Keys are managed in the dashboard - shown once on creation, rotate or deactivate any time. See foura.ai/docs/getting-started/authentication for the full key-management walkthrough.

Error envelope - typed contract for agent retries

Every error (isError: true) carries a structuredContent envelope with at minimum these three fields:

jsonc

{
  "service": "single" | "proxy" | "browser",
  "code": "ssrf_blocked" | "auth_failed" | "rate_limited" | ...,
  "error": "Human-readable message"
}

Where 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}.

`code`	When	Retry safe?
`ssrf_blocked`	Target IP in a private / reserved range (RFC 5735+6598+IPv6 reserved)	No - change the URL
`upstream_non_json`	Upstream returned malformed body	Maybe - investigate
`bad_request` (400)	Input shape rejected by FourA	No - fix arguments
`auth_failed` (401)	Key missing, invalid, or deactivated	No - fix the key
`forbidden` (403)	Authenticated but not allowed	No
`not_found` (404)	Target / endpoint doesn't exist	No
`rate_limited` (429)	RPM cap hit	Yes - wait `retryAfter`
`at_capacity` (503)	Concurrency cap hit	Yes - wait `retryAfter`
`service_disabled` (503)	Maintenance window	Yes - wait `retryAfter`
`service_unavailable` (503)	Generic 503	Yes - short backoff
`upstream_error` (≥500)	Upstream 5xx	Yes - exponential backoff
`upstream_client_error` (4xx)	Other 4xx	Usually no

LLM agents can read code directly for retry logic without parsing prose. Spec reference: foura.ai/docs/api/errors.

Combining the tools - sticky exit IPs

The 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.

jsonc

// 1. Find a working exit for the target - use maxTries:25-30 for tier-1 WAFs
const r = await foura_proxy({
  maxTries: 30,
  request: { method: "GET", url: "https://probe.example.com", unblocker: true }
});
// → { status: 200, proxy: "4DZ3VE", ... }

// 2. Reuse it for follow-up HTTP (cookies, multi-step flows)
await foura_single({ method: "GET", url: "https://target/api", proxy: r.proxy });

// 3. Or render JS through the same egress - exits through the IP that already
//    cleared the challenge for this target, so the snapshot captures the real
//    post-challenge content instead of a challenge page.
await foura_browser({ url: "https://target/spa", proxy: r.proxy });

This 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.

To 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.

Large responses - `offload_large` (default: inline)

By default (since v0.2.0), full response bodies are returned inline in structuredContent regardless of size. This works in every MCP client.

If 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.

jsonc

{
  "method": "GET",
  "url": "https://en.wikipedia.org/wiki/Web_scraping",
  "offload_large": true   // opt in for token savings
}

Client	`offload_large: true`
Claude Desktop	not yet - leave default `false`
Claude Code, Cursor, Windsurf	supported
VS Code MCP extension	supported

Tenant-isolated: only the API key that stored a payload can read it back.

Other limits

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.
Rate limits are enforced by the FourA API per service. Concurrency + RPM. Details at foura.ai/docs/api/rate-limits.
Body size cap of 256 KB on incoming /mcp requests (real MCP payloads are < 4 KB).
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.

Self-Hosting

The 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.

Configurable environment:

Variable	Default	Purpose
`PORT`	`3076`	HTTP listen port
`FOURA_API_BASE`	`https://api.foura.ai/api`	Upstream FourA REST base URL
`FOURA_MCP_PAYLOADS_DIR`	`/data/payloads`	Where ≥50 KB responses are cached on disk

The full source is public here under MIT - build the container from the included Dockerfile (docker build -t foura-mcp .), or run it straight from npm with npx -y @fouradata/mcp. See DEVELOPMENT.md for the local build and test workflow.

License

MIT. See LICENSE.

Install

Configuration

Environment variables

FOURA_API_KEYrequiredsecret

Your FourA API key (pk_live_...), created at https://foura.ai/dashboard/#api-keys

claude_desktop_config.json

{
  "mcpServers": {
    "mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@fouradata/mcp@0.4.8"
      ],
      "env": {
        "FOURA_API_KEY": "<YOUR_FOURA_API_KEY>"
      }
    }
  }
}

Topics

foura_single

foura_proxy

foura_browser

foura_auto

@fouradata/mcp

Quick Start - local stdio (recommended for Claude Desktop)

Quick Start - hosted (Streamable HTTP)

The Tools

foura_auto - smart fetch (the default)

foura_single - fast HTTP

foura_proxy - rotating proxies with retry

foura_browser - full browser session

Built-in Prompts

Authentication

Error envelope - typed contract for agent retries

Combining the tools - sticky exit IPs

Large responses - offload_large (default: inline)

Other limits

Self-Hosting

License

Links

Install

Configuration

`foura_auto` - smart fetch (the default)

`foura_single` - fast HTTP

`foura_proxy` - rotating proxies with retry

`foura_browser` - full browser session

Large responses - `offload_large` (default: inline)