MCP Server

Verwende FourA von jedem Model Context Protocol Client (Claude Desktop, Claude Code, Cursor, Windsurf, VS Code) als vier native Tools und sechs Workflow-Prompts. Kein Integrationscode, kein benutzerdefinierter HTTP-Client.

Open Source auf GitHub; auf npm als @fouradata/mcp. Aktuelles Release: 0.5.0.

Quick Start: local stdio (empfohlen für Claude Desktop)

Hole dir einen Key unter foura.ai/dashboard#api-keys (ein Klick, wird nur bei der Erstellung angezeigt, Format pk_live_...). Füge dies in die Config deines MCP-Clients ein:

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

Claude Desktop Falle: Beende Claude Desktop vollständig (Cmd+Q unter macOS), bevor du die Config-Datei bearbeitest. Wenn die App noch läuft, überschreibt sie beim Beenden deine Änderungen mit ihrer In-Memory-Config.

Der Befehl npx lädt @fouradata/mcp beim ersten Start herunter und führt es als Subprocess deines MCP-Clients aus. Keine globale Installation nötig.

Client	Speicherort der Config
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` (zuerst `FOURA_API_KEY` in der Umgebung setzen)
Cursor	`~/.cursor/mcp.json`
Windsurf	`~/.codeium/windsurf/mcp_config.json`
VS Code (MCP-Erweiterung)	`.vscode/mcp.json`

Starte den Client neu. Die Tools (foura_auto, foura_single, foura_proxy, foura_browser) und sechs Prompts erscheinen in deiner Tool-Liste.

Quick Start: Hosted (Streamable HTTP)

Für Clients, die den Streamable HTTP-Transport unterstützen (Cursor, Windsurf, VS Code, Claude Code mit --transport http), verweise diese auf den Hosted Endpoint, anstatt einen lokalen Subprocess auszuführen:

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

Verwende für Claude Desktop die obige stdio config oder verbinde den gehosteten endpoint über mcp-remote:

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

Referenz für gehostete Endpunkte

Eigenschaft	Wert
URL	`https://mcp.foura.ai/mcp`
Transport	Streamfähiges HTTP (POST `/mcp`, SSE-Responses)
Authentifizierung	`Authorization: Bearer pk_live_...` pro Request
MCP-Protocol-Version	Gemäß `@modelcontextprotocol/sdk` (aktuell `2025-11-25`, `2025-06-18`, `2025-03-26`, `2024-11-05`, `2024-10-07`)
401-Challenge	`WWW-Authenticate: Bearer realm="foura-mcp", resource_metadata="https://foura.ai/docs/mcp/server#auth"`

Der gehostete Server ist zustandslos. Jeder Request bringt seinen eigenen Key mit, den der Server als X-API-Key an die FourA API weiterleitet. Ein Key öffnet alle vier Tools.

Zum Schutz vor DNS-Rebinding (CVE-2025-66414) validiert der Server den Header Host (muss mcp.foura.ai oder localhost sein) und den Header Origin, falls vorhanden (auf der Allowlist: mcp.foura.ai, claude.ai, app.cursor.sh, app.cursor.com). Server-to-Server-Aufrufer (curl, MCP-Clients im stdio-Bridge-Modus) senden kein Origin und passieren direkt.

Tools

Alle vier Tools sind als readOnlyHint: true und openWorldHint: true gemäß der MCP 2025-06-18 Spezifikation annotiert. Clients, die vertrauenswürdige Read-Only-Tools automatisch genehmigen, rufen sie ohne Bestätigungsdialog pro Request auf.

foura_auto ist der intelligente Standard: Übergib ihm eine URL und es liefert den Inhalt zurück, wobei es die Fetch-Methode für dich auswählt. Die anderen drei sind Low-Level-Primitive, die es orchestriert; nutze sie, wenn du explizite Kontrolle möchtest.

foura_auto

Übergib ihm eine URL, wenn FourA die Request-Methode auswählen soll. Es unternimmt eine begrenzte Anzahl an Versuchen über die verfügbaren HTTP-, Proxy- und Browser-Pfade. Übergib validate bei geschützten Zielen, damit die Response Inhalte enthalten muss, die die echte Seite identifizieren. Wenn kein Versuch die Validierung erfüllt, gibt das Tool einen Fehler zurück, anstatt eine Challenge-Seite als Erfolg zu präsentieren.

Die Response enthält Abschlussdetails in meta und standardmäßig eine wiederverwendbare session mit proxy, cookies und userAgent. Für ein einfaches Follow-up rufe foura_single mit session.proxy als proxy auf, serialisiere die Cookies als einen Cookie-Header und sende session.userAgent als User-Agent-Header. Für JavaScript-Rendering übergibst du die Session-Werte an die passenden foura_browser-Felder.

foura_single

Ein HTTP-Request, eine Response zurück. Spiegelt POST /api/single/ eins zu eins wider.

Nutze dies für statische Seiten, JSON APIs und serverseitig gerendertes HTML.

Auswahl des zu präsentierenden Browsers

Ein Request präsentiert standardmäßig den neuesten Google Chrome. Wenn ein Ziel einen Browser akzeptiert und einen anderen ablehnt, setze browser (Chrome, Edge, Safari, Firefox oder Tor), os (Windows, macOS, Android oder iOS) oder version, oder übergib eine exakte profile-ID:

{
  "method": "GET",
  "url": "https://example.com",
  "browser": "Firefox",
  "os": "Windows"
}

Die neueste Version gewinnt, wenn mehrere Profile übereinstimmen. Eine nicht existierende Kombination gibt einen Fehler mit den verfügbaren Optionen zurück, sodass ein Request nie als ein Browser gesendet wird, den du nicht ausgewählt hast. Die Auswahl erfordert unblocker, was standardmäßig aktiviert ist. Der Katalog wird unter GET /api/profiles veröffentlicht und benötigt keinen API-Key.

Die gleichen vier Felder befinden sich im Objekt request von foura_proxy.

foura_proxy

Leite einen HTTP-Request über rotierende Proxys mit automatischem Retry weiter. Verwende dies, wenn foura_single blockiert ist oder das Ziel ein bestimmtes Exit-Land erfordert.

Setze exitCountries auf eine strikte Allowlist von zielseitig sichtbaren Zwei-Buchstaben-Ländercodes, die vom Benutzer oder den Zielanforderungen vorgegeben werden:

{
  "maxTries": 5,
  "exitCountries": ["CZ", "GB"],
  "request": {
    "method": "GET",
    "url": "https://example.com/pricing",
    "browser": "Chrome",
    "os": "Windows"
  }
}

Werte werden getrimmt, in Großbuchstaben umgewandelt und dedupliziert. Proxies mit unbekannten Exits werden ausgeschlossen, und der Request fällt nie auf ein nicht angefordertes Land zurück. Die Auswahl nutzt die neuesten verfügbaren, für das Ziel sichtbaren Länder-Metadaten, die normalerweise innerhalb von zehn Minuten aktualisiert werden. Es handelt sich nicht um ein Live-Geolocation-Lookup während des Requests. Leite das bereitstellende Land nicht aus der Proxy-Host-Adresse ab.

Ein Scoped Success gibt exitCountry und die wiederverwendbare proxy ID zurück. Prüfe, ob exitCountry zur angeforderten Allowlist gehört. Wenn der aktuelle Pool keinen Treffer hat, gibt das Tool code: "no_eligible_proxy" mit dem normalisierten Scope in details.exitCountries zurück. Behalte diesen Scope bei und versuche es später erneut. Ändere oder erweitere ihn nur, wenn der Benutzer die Anforderung explizit ändert.

Wenn die ausgewählte Seite später JavaScript benötigt, übergebe die zurückgegebene proxy ID an foura_browser.proxy, damit der Browser denselben Exit wiederverwendet.

foura_browser

Vollständige Browser-Session. JavaScript wird ausgeführt, das DOM gerendert, Cookies kommen zurück. Spiegelt POST /api/browser/.

Verwende dies für Single-Page-Apps, Lazy-Loading-Inhalte oder Seiten hinter Anti-Bot-Challenges, die einen echten Browser zum Lösen benötigen.

Informationen zu Input-Shapes, Defaults und Validierungsregeln für jedes Tool findest du in der REST-Endpoint-Referenz. Die Tool-Schemas stimmen Feld für Feld mit der REST-API überein, zuzüglich des MCP-exklusiven offload_large Opt-ins (siehe unten).

Wenn ein Ziel einen Bot-Check durchführt

foura_single und foura_proxy geben defense zurück, wenn das Ziel auf dem Weg zum Body einen Bot-Check durchgeführt hat. defense.solved: true bedeutet, dass der Check bestanden wurde und data die eigentliche Seite ist. false bedeutet, dass der Body möglicherweise eine Challenge-Seite ist. Versuche es mit einem anderen Browser, Betriebssystem oder einer anderen Version erneut, oder wechsle zu foura_proxy oder foura_browser, anstatt die Challenge-Seite als Inhalt zu behandeln.

Typisierte Responses

Jede Tool-Response enthält sowohl content (menschenlesbare Textzusammenfassung) als auch structuredContent (typisiertes JSON, das gegen das outputSchema des Tools validiert wurde). Jedes Tool hat sein eigenes, einzigartiges Shape:

foura_auto: single-shaped { status, headers, data } plus meta ({ rung, solved, attempts, credits }, immer vorhanden, wobei rung einer von cache, probe, proxy, browser, fail ist) und standardmäßig session ({ proxy, cookies, userAgent }) für ein Replay durch die Lower-Level-Tools. Kein total_time.
foura_single: { status, headers, data, total_time, ... } (Headers ist ein Array, ein Eintrag pro Redirect-Hop)
foura_proxy: identisch mit Single plus { proxy, total }; ein Scoped Success enthält auch exitCountry
foura_browser: eigenes Shape { status, headers: object, body, cookies, userAgent } (Hinweis: body kann je nach Content-Type ein String oder ein Object sein)

Clients, die structuredContent unterstützen, können das typisierte Object direkt an das LLM übergeben, anstatt von diesem zu verlangen, JSON aus Fließtext zu parsen.

Mehrwertige Response-Headers

Headers, die mehrfach vorkommen (Set-Cookie, Link, WWW-Authenticate), kommen als Arrays zurück:

{
  "headers": [
    {
      "result": { "version": "HTTP/2", "code": 200, "reason": "" },
      "content-type": "text/html",
      "set-cookie": ["a=1; Path=/", "b=2; Path=/"]
    }
  ]
}

Dies ist wichtig für Websites, die Session-, Tracking- und Consent-Cookies in einer Response setzen (die meisten E-Commerce-Websites).

Große Responses: `offload_large` (Standard: inline)

Standardmäßig (seit v0.2.0) werden vollständige Response-Bodys unabhängig von der Größe inline in structuredContent zurückgegeben. Dies funktioniert in jedem MCP-Client ohne weitere Konfiguration.

Wenn dein Client MCP resources/read unterstützt UND du bei großen Seiten Tokens sparen möchtest, übergib offload_large: true pro Tool-Aufruf. Responses >= 50 KB werden dann auf die Festplatte geschrieben, als resource_link zurückgegeben, und dein Client ruft den Body nur ab, wenn er ihn tatsächlich benötigt. Gecachte Payloads laufen nach 1 Stunde ab.

{
  "method": "GET",
  "url": "https://en.wikipedia.org/wiki/Web_scraping",
  "offload_large": true
}

Client	`offload_large: true`
Claude Desktop	noch nicht, Standard `false` belassen
Claude Code, Cursor, Windsurf	unterstützt
VS Code MCP extension	unterstützt

Mandanten-isoliert: Jeder API-Key erhält seinen eigenen Namespace (sha256(apiKey)[:16]). Nur der Key, der einen Payload gespeichert hat, kann ihn wieder auslesen. Mandantenübergreifende Lesezugriffe geben Payload not found zurück, ohne die Existenz von Daten preiszugeben.

Integrierte Prompts

Sechs Workflow-Vorlagen erscheinen unter /prompts in jedem MCP-Client. Jede akzeptiert benannte Argumente und gibt eine als Vorlage formatierte Benutzernachricht zurück, die eines oder mehrere Tools orchestriert.

Prompt	Argumente	Funktion
`smart_fetch`	`url`, optional `must_contain`, `extract`	Auto-Fetch (wählt die Methode, handhabt Bot-Schutz), gibt danach den Inhalt zurück oder extrahiert ihn
`scrape_product_page`	`url`	Browser-Fetch, extrahiert danach Produkttitel, Preis, Bild, Bestand, SKU als JSON
`extract_article`	`url`	Single mit Proxy-Fallback, entfernt danach Nav/Ads und gibt sauberes Artikel-JSON zurück
`monitor_pricing`	`url`, optional `target_price`	Proxy-Fetch, extrahiert aktuellen Preis, vergleicht mit Ziel
`check_endpoint_health`	`url`, optional `expected_text`	Single mit strenger Validierung, gibt Erreichbarkeit und Timing zurück
`bulk_fetch_urls`	`urls` (kommagetrennt)	Paralleler Single, Auto-Fallback zu Proxy pro URL, gibt nur Metadaten zurück

Prompts kosten im Leerlauf null Tokens. Nur aufgerufene Prompts fließen in den LLM-Kontext ein.

Volltext plus manuelle Fallback-Prompts: MCP Recipes.

Error-Envelope

Jeder Fehler (isError: true) enthält ein structuredContent-Envelope. Mindestfelder bei jedem Fehler:

{
  "service": "auto | single | proxy | browser",
  "code": "rate_limited",
  "error": "Rate limit exceeded"
}

Bei Upstream-Fehlern mit HTTP-Status ist auch status vorhanden. Bei Rate-Limit- und Kapazitätsfehlern fügt der Upstream-Envelope retryAfter, current.{concurrency, rpm} und limits.{maxConcurrency, maxRpm} hinzu. Siehe API Errors für die zugrunde liegende REST-Form.

Stabile code-Werte:

Code	HTTP	Bedeutung	Retry sicher?
`ssrf_blocked`	n/a	Ziel-IP in einem privaten oder reservierten Bereich (RFC 5735, 6598, IPv6 reserviert)	Nein, URL ändern
`upstream_non_json`	variiert	Upstream hat fehlerhaften Body zurückgegeben	Vielleicht, untersuchen
`output_validation_failed`	n/a	Die `outputSchema` des MCP-Servers hat die Upstream-Response abgelehnt (Server-Bug oder unerwartete Upstream-Form)	Vielleicht, melden
`bad_request`	400	Input-Form abgelehnt	Nein, Argumente korrigieren
`auth_failed`	401	Key fehlt, ist ungültig oder deaktiviert	Nein, den Key korrigieren
`forbidden`	403	Authentifiziert, aber nicht erlaubt	Nein, oder zu `foura_proxy` wechseln
`not_found`	404	Ziel oder Endpoint fehlt	Nein
`rate_limited`	429	RPM-Limit erreicht	Ja, warten `retryAfter`
`at_capacity`	503	Concurrency-Limit erreicht	Ja, warten `retryAfter`
`service_disabled`	503	Wartungsfenster oder dein Plan enthält dieses Tool nicht	Support kontaktieren
`service_unavailable`	503	Generischer 503	Ja, kurzes Backoff
`upstream_error`	500+	Upstream 5xx	Ja, exponentielles Backoff
`upstream_client_error`	4xx	Andere 4xx	Meistens nein
`upstream_unknown`	andere	Defensiv, sollte in der Praxis nicht auftreten	Untersuchen
`no_eligible_proxy`	n/a	Kein Proxy entspricht dem strikten `exitCountries`-Scope	Später erneut versuchen; Scope nur explizit ändern

LLM-Agenten können code direkt für die Retry-Logik lesen, ohne Text zu parsen. Authentifizierungs-Walkthrough: Authentication.

Limits

Standardmäßig Inline-Body. Mit offload_large: true gehen Responses >= 50 KB auf die Festplatte + resource_link (pro Tenant, 1 Stunde TTL).
Private Ziele werden auf der MCP-Ebene abgelehnt (RFC 5735, RFC 6598, IPv6-reservierte Blöcke). Nur öffentliche Hosts werden weitergeleitet.
Request-Body-Limit von 256 KB bei eingehenden /mcp-Requests (echte MCP-Payloads sind < 4 KB).
Rate Limits werden von der FourA API pro Service durchgesetzt. Siehe Rate Limits.

Self-Hosting

Der vollständige Server-Quellcode ist öffentlich auf GitHub unter @fouradata/mcp. Klone das Repo, npm install, npm run build, und führe node dist/http.js aus, um deine eigene Instanz aufzusetzen. Läuft zustandslos in einem einzelnen Container hinter jedem Load Balancer.

Konfigurierbare Umgebung:

Variable	Standard	Zweck
`PORT`	`3076`	HTTP-Listen-Port
`FOURA_API_BASE`	`https://api.foura.ai/api`	Upstream FourA REST Base-URL
`FOURA_MCP_PAYLOADS_DIR`	`/data/payloads`	Wo Responses >= 50 KB auf der Festplatte gecacht werden (mit `offload_large: true`)
`FOURA_MCP_ALLOWED_HOSTS`	`mcp.foura.ai,localhost,127.0.0.1,[::1]`	Hostname-Allowlist für den Header `Host` (Schutz vor DNS-Rebinding)
`FOURA_MCP_ALLOWED_ORIGINS`	`https://mcp.foura.ai,https://claude.ai,https://app.cursor.sh,https://app.cursor.com`	Origin-Allowlist für Browser-Aufrufe
`FOURA_MCP_RESOURCE_METADATA_URL`	`https://foura.ai/docs/mcp/server#auth`	URL, die bei 401 in `WWW-Authenticate` zurückgegeben wird

Der offizielle Container läuft als uid 1001 (nicht als root). Der Host-Bind-Mount /data/payloads muss für diese UID beschreibbar sein.

Skaliere horizontal hinter jedem Load Balancer. Clients übermitteln ihren Key bei jedem Request, es gibt also keine Sticky Sessions.

Aktualisiert: 6. August 2026

MCP Server

MCP Server

Quick Start: local stdio (empfohlen für Claude Desktop)

Quick Start: Hosted (Streamable HTTP)

Referenz für gehostete Endpunkte

Tools

foura_auto

foura_single

Auswahl des zu präsentierenden Browsers

foura_proxy

foura_browser

Wenn ein Ziel einen Bot-Check durchführt

Typisierte Responses

Mehrwertige Response-Headers

Große Responses: offload_large (Standard: inline)

Integrierte Prompts

Error-Envelope

Limits

Self-Hosting

Große Responses: `offload_large` (Standard: inline)