# MCP Server

> URL: https://foura.ai/de/docs/mcp/server
> Updated: 2026-11-13
> Index: https://foura.ai/llms.txt

# MCP-Server

Nutze FourA über jeden Client für das [Model Context Protocol](https://modelcontextprotocol.io) (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](https://github.com/fouradata/mcp); auf [npm](https://www.npmjs.com/package/@fouradata/mcp) als `@fouradata/mcp`. Aktuelles Release: `0.8.3`.

## Schnellstart: lokales stdio (empfohlen für Claude Desktop)

Hole dir einen Key unter [foura.ai/dashboard#api-keys](https://foura.ai/dashboard#api-keys) (ein Klick, Format `pk_live_...`, und **Reveal** zeigt den Key später wieder an). Füge dies in die Konfiguration deines MCP-Clients ein:

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

> **Claude Desktop Fallstrick:** Beende Claude Desktop vollständig (`Cmd+Q` unter macOS), **bevor** du die Konfigurationsdatei bearbeitest. Wenn die App noch läuft, überschreibt sie deine Änderungen beim Beenden mit ihrer Konfiguration aus dem Arbeitsspeicher.

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

| Client | Speicherort der Konfiguration |
|---|---|
| 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` (setze zuerst `FOURA_API_KEY` in der Umgebung) |
| Cursor | `~/.cursor/mcp.json` |
| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
| VS Code (MCP-Erweiterung) | `.vscode/mcp.json`, unter einem Top-Level-Schlüssel `servers` statt `mcpServers` |

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

## Schnellstart: gehostet (Streamable HTTP)

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

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

Nutze für Claude Desktop die obige stdio-Konfiguration oder binde den gehosteten Endpoint über `mcp-remote` an:

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

## Hosted Endpoint-Referenz

| Eigenschaft | Wert |
|---|---|
| URL | `https://mcp.foura.ai/mcp` |
| Transport | Streamable HTTP (POST `/mcp`, SSE-Antworten) |
| Authentifizierung | `Authorization: Bearer pk_live_...` pro Request. Ein einfacher Key in `Authorization` oder `X-API-Key: pk_live_...` funktioniert ebenfalls |
| 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"` |

Die 401 Challenge enthält bewusst keinen Parameter gemäß RFC 9728 `resource_metadata`. Wird dieser Parameter angegeben, startet ein OAuth-fähiger Client einen Flow, den dieser Server nicht implementiert. Sende deinen `pk_live_`-Key als Bearer-Token, und der 401-Fehler verschwindet.

Der gehostete Server ist zustandslos. Jeder Request übermittelt seinen eigenen Key, den der Server als `X-API-Key` an die FourA-API weiterleitet. Ein Key schaltet alle vier Tools frei.

Zum Schutz vor DNS-Rebinding (CVE-2025-66414) validiert der Server den `Host`-Header (muss `mcp.foura.ai` oder localhost sein) sowie den `Origin`-Header, sofern vorhanden (auf der Positivliste: `mcp.foura.ai`, `claude.ai`, `app.cursor.sh`, `app.cursor.com`). Server-zu-Server-Aufrufer (`curl`, MCP-Clients im stdio-Bridge-Modus) senden keinen `Origin` und werden direkt durchgeleitet.

## Tools

Alle vier Tools sind gemäß der [MCP-Spezifikation vom 18.06.2025](https://modelcontextprotocol.io/specification/2025-06-18/server/tools) mit `readOnlyHint: true` und `openWorldHint: true` annotiert. Clients, die vertrauenswürdige Read-Only-Tools automatisch genehmigen, rufen sie ohne Bestätigungs-Modal pro Request auf.

`foura_auto` ist der intelligente Standard: Übergib eine URL und das Tool liefert den Inhalt zurück, wobei es die Fetch-Methode für dich auswählt. Die anderen drei Tools sind die Low-Level-Primitive, die es orchestriert. Nutze sie, wenn du explizite Kontrolle benötigst.

### foura_auto

Übergib eine URL, wenn FourA die Request-Methode wählen soll. Das Tool führt begrenzte Versuche über die verfügbaren HTTP-, Proxy- und Browser-Pfade durch. Übergib `validate` bei geschützten Zielen, damit die Response zwingend Inhalt enthält, der die echte Seite identifiziert. Erfüllt kein Versuch die Validierung, gibt das Tool einen Fehler zurück, anstatt eine Challenge-Seite als Erfolg zu werten.

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

Setze `exitClass: "premium"`, damit Auto auf einen Premium-Exit eskaliert, sobald der Standard-Pool die Seite nicht erreichen kann. Sowohl `exitClass: "standard"` als auch das Weglassen des Feldes belassen Auto im Standard-Pool, und nur ein Request, der eine Klasse benennt, erhält `exitClass` zurück. Es funktioniert wie bei `foura_proxy`: Es ist eine Freigabe, keine Anweisung, wird auf den Premium-Traffic deines Plans angerechnet und bei einem Plan ohne Premium-Exits mit `code: "plan_limit_premium"` abgelehnt. Der Wert `exitClass` des Ergebnisses gibt an, welche Klasse geliefert hat. Siehe [exitClass bei Smart Fetch](https://foura.ai/docs/api/endpoints#exitclass-on-smart-fetch).

### foura_single

Ein HTTP-Request, Response zurück. Spiegelt [`POST /api/single/`](https://foura.ai/docs/api/endpoints) eins zu eins wider.

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

#### Browser-Darstellung auswählen

Ein Request gibt sich standardmäßig als das neueste Google Chrome aus. 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:

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

Passen mehrere Profile, gewinnt die neueste Version. Eine nicht existierende Kombination gibt einen Fehler mit den verfuegbaren Optionen zurueck. So wird kein Request als Browser gesendet, den du nicht gewaehlt hast. Die Auswahl erfordert `unblocker`, was standardmaessig aktiv ist. Der Katalog ist unter [`GET /api/profiles`](https://foura.ai/docs/api/endpoints) veroeffentlicht und erfordert keinen API-Key.

Dieselben vier Felder befinden sich im `request`-Objekt von `foura_proxy`.

### foura_proxy

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

Setze `exitCountries` auf eine strikte Allowlist zweistelliger, fuer das Ziel sichtbarer Laendercodes, vorgegeben durch den Nutzer oder die Zielanforderungen:

```json
{
  "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. Exits des Standard-Pools mit unbekanntem Land werden ausgeschlossen, und der Standard-Pool fällt niemals auf ein nicht angefordertes Land zurück. Ein Premium-Exit bleibt ebenfalls innerhalb der Liste: Bei `exitClass: "premium"` startet weiterhin zuerst der Standard-Pool, und ein Premium-Exit geht von einem deiner Länder aus und benennt es in `exitCountry`. Die Auswahl nutzt die neuesten verfügbaren, für das Ziel sichtbaren Ländermetadaten, die normalerweise innerhalb von zehn Minuten aktualisiert werden. Es handelt sich nicht um einen Live-Geolokalisierungs-Lookup während des Requests. Leite das bereitstellende Land nicht von der Proxy-Host-Adresse ab.

Ein erfolgreicher Request mit Scope liefert `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 Nutzer die Anforderung explizit ändert. Country-Scoping ist ab dem Startup-Plan enthalten. In einem Plan ohne dieses Feature wird ein Aufruf mit `exitCountries` mit `403` und `X-FourA-Limit: plan_limit_feature` abgelehnt.

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

Setze `exitClass: "premium"` für ein Ziel, das der Standard-Pool unabhängig von der Anzahl der versuchten Exits nicht erreichen kann. Es ist eine Erlaubnis, keine Anweisung: Der Standard-Pool konkurriert weiterhin um die Antwort und gewinnt meistens, und ein Request, den er vor dem Versuch eines Premium-Exits beantwortet, verbraucht keinen Premium-Traffic. Ein Premium-Versuch zählt den übertragenen Traffic auch dann, wenn er fehlschlägt. Die Response meldet `exitClass` zurück, `premium` oder `standard`, sodass du pro Request siehst, welche Klasse dich bedient hat. `standard` ist auch das Ergebnis, sobald der in deinem Plan enthaltene Premium-Traffic aufgebraucht ist, und stellt ein normales Ergebnis dar, keinen Fehler. `exitClass: "standard"` verbietet eine Eskalation vollständig. `exitClass: "premium"` wird in einem Plan ohne Premium-Exits mit `code: "plan_limit_premium"` abgelehnt. Siehe [exitClass](https://foura.ai/docs/api/endpoints#exitclass).

Musste die Rotation zu einem anderen Browser wechseln, um eine Antwort zu erhalten, enthält eine erfolgreiche Response `profile`: die ausgewählte Katalog-Profil-ID. Übergib sie beim nächsten Aufruf als `profile`, um denselben Browser zu präsentieren.

Eine fehlgeschlagene Rotation enthält `attemptReport` neben dem Fehler: einen `summary`-Satz plus Zähler, die Exits trennen, die nie geantwortet haben (`noResponse`), Exits, die ein Bot-Check abgelehnt hat (`defense`, mit den Anbietern in `vendors`), Seiten, die ankamen und nur durch deine eigene `validate.data` verworfen wurden (`contentRejected`), `statusRejected` und `other`. `profilesTried` listet die vom Task gesendeten Browser in der Reihenfolge ihrer ersten Verwendung auf, wobei `default` bedeutet, dass der Request genau wie verfasst gesendet wurde. Ein hoher Wert für `contentRejected` bedeutet, dass FourA echte Seiten geliefert hat und deine eigene Regel sie verworfen hat. Siehe [Why a Proxy Request Ran Out of Tries](https://foura.ai/docs/troubleshooting/proxy-attempt-report).

### foura_browser

Vollständige Browser-Session. JavaScript wird ausgeführt, das DOM gerendert, Cookies werden zurückgegeben. Spiegelt [`POST /api/browser/`](https://foura.ai/docs/api/endpoints) wider.

Nutze dies für Single-Page-Apps, Lazy-Loaded-Inhalte oder Seiten mit einer Überprüfung, die einen echten Browser erfordert.

Eingabeformate, Standardwerte und Validierungsregeln für jedes Tool findest du in der [REST-Endpoint-Referenz](https://foura.ai/docs/api/endpoints). Die Tool-Schemas entsprechen der REST-API, zuzüglich des MCP-exklusiven `offload_large`-Opt-ins (siehe unten), mit zwei Ausnahmen: `foura_browser` hat kein `lean`-Feld und `foura_proxy` bietet derzeit keine [Exit-Location](https://foura.ai/docs/api/endpoints#exit-location)-Felder. Ein unter diesen Namen übergebener Wert erreicht die API nie. Um einen festzulegen, rufe [`POST /api/browser/`](https://foura.ai/docs/api/endpoints) oder [`POST /api/proxy/`](https://foura.ai/docs/api/endpoints) direkt auf.

### Wenn ein Ziel eine Bot-Prüfung ausführt

`foura_single` und `foura_proxy` geben `defense` zurück, wenn das Ziel auf dem Weg zum Body eine Bot-Prüfung durchgeführt hat. `defense.solved: true` bedeutet, dass die Prüfung bestanden wurde und `data` die echte Seite ist; `false` bedeutet, dass der Body eine Challenge-Seite sein kann. 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 verarbeiten.

## Typisierte Responses

Jede Tool-Response enthält sowohl `content` (menschenlesbare Textzusammenfassung) als auch `structuredContent` (typisiertes JSON, validiert gegen das `outputSchema` des Tools). Jedes Tool hat seine eigene, eindeutige Struktur:

- `foura_auto`: Single-Struktur `{ status, headers, data }` plus `meta` (`{ rung, solved, attempts, credits, attemptsByEngine, browserRequests }`, immer vorhanden, wobei `rung` eines von `cache`, `probe`, `proxy`, `browser`, `warmup`, `fail` ist) und standardmäßig `session` (`{ proxy, cookies, userAgent }`) für die Wiederholung über die Low-Level-Tools; ein Request mit einer angegebenen Klasse enthält außerdem `exitClass`. `meta.attemptsByEngine` zählt die Requests, die der Aufruf an Single, Proxy und Browser gesendet hat, und `meta.browserRequests` zählt jene, die dein tägliches Browser-Kontingent verbraucht haben. Ein Fehlschlag enthält zudem `attemptReport`. Kein `total_time`.
- `foura_single`: `{ status, headers, data, total_time, ... }` (Headers ist ein Array, ein Eintrag pro Redirect-Hop)
- `foura_proxy`: wie Single plus `{ proxy, total }`; ein erfolgreicher Scope-Request enthält zudem `exitCountry`, ein Request mit einer angegebenen Klasse enthält `exitClass`, eine Rotation mit Wechsel der Browser-Familie enthält `profile` und ein Fehlschlag enthält `attemptReport`
- `foura_browser`: eigenständige Struktur `{ status, headers: object, body, cookies, userAgent }` (Hinweis: `body` kann je nach Content-Type ein String oder ein Objekt sein)

Jedes Tool meldet außerdem die Kosten des Aufrufs und Informationen zum Tracing, ausgelesen aus den Response-Headern der API:

- `credits`: Credits, die dieser Call verbraucht hat. Auch bei Fehlern vorhanden, da die Arbeit dennoch ausgeführt wurde. Du zahlst nur für erfolgreiche Calls; ein Fehler zeigt hier also seine Credits an, kostet dich aber nichts.
- `request_id`: FourAs ID für den Call. Gib sie bei Support-Anfragen an.
- `exitClass`: `premium`, wenn ein Premium-Exit den Call bedient hat. Bei `foura_single` und `foura_browser` passiert das, wenn `proxy` einen Premium-Exit wiederholt, den `foura_proxy` oder `foura_auto` gefunden hat.

Jeder Wert fehlt, wenn die API nichts gemeldet hat. Ein Client für eine ältere Version funktioniert also unverändert weiter. Dieselben Werte sind unter [Response Headers](https://foura.ai/docs/api/response-headers) dokumentiert.

Clients, die `structuredContent` unterstützen, können das typisierte Objekt direkt an das LLM übergeben, anstatt JSON aus Fließtext parsen zu müssen.

### Mehrwertige Response-Header

Header, die mehrfach vorkommen (`Set-Cookie`, `Link`, `WWW-Authenticate`), werden als Arrays zurückgegeben:

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

Das ist wichtig für Websites, die Session-, Tracking- und Consent-Cookies in einer einzigen Response setzen (der Großteil des E-Commerce).

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

Standardmäßig (seit v0.2.0) werden vollständige Response-Bodies unabhängig von ihrer Größe inline in `structuredContent` zurückgegeben. Das funktioniert in jedem MCP-Client direkt ab Werk.

Wenn dein Client MCP-`resources/read` unterstützt UND du bei großen Seiten Tokens sparen möchtest, übergib `offload_large: true` pro Tool-Call. Responses ab 50 KB werden dann auf die Festplatte geschrieben und als `resource_link` zurückgegeben, sodass dein Client den Body nur dann abruft, wenn er ihn wirklich benötigt. Auf dem gehosteten Server laufen gecachte Payloads nach 1 Stunde ab. Auf deiner eigenen Instanz löscht nichts gespeicherte Payloads: Lösche Dateien, die älter als eine Stunde sind, selbst aus dem Payload-Verzeichnis.

Ein ausgelagertes Ergebnis enthält `offloaded_resource_uri` und `size_bytes` anstelle des Bodys. Ein ausgelagertes Ergebnis lässt zudem `defense` sowie `profile` bei `foura_proxy` weg; verzichte daher bei einem Call, der diese Felder liest, auf `offload_large`.

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

| Client | `offload_large: true` |
|---|---|
| Claude Desktop | noch nicht, Standard `false` beibehalten |
| Claude Code, Cursor, Windsurf | unterstützt |
| VS Code MCP-Erweiterung | unterstützt |

Mandantenisoliert: Jeder API-Schlüssel erhält einen eigenen Namespace (`sha256(apiKey)[:16]`). Nur der Schlüssel, der ein Payload gespeichert hat, kann es wieder auslesen. Mandantenübergreifende Lesezugriffe geben `Payload not found` zurück, ohne Rückschlüsse auf die Existenz zuzulassen.

## Integrierte Prompts

Sechs Workflow-Vorlagen stehen unter `/prompts` in jedem MCP-Client zur Verfügung. Jede Vorlage nimmt benannte Argumente entgegen und gibt eine vorgefertigte User-Nachricht zurück, die ein oder mehrere Tools orchestriert.

| Prompt | Argumente | Funktion |
|---|---|---|
| `smart_fetch` | `url`, optional `must_contain`, `extract` | Automatischer Abruf (wählt die Methode, umgeht Bot-Schutz), danach Rückgabe oder Extraktion des Inhalts |
| `scrape_product_page` | `url` | Browser-Abruf, extrahiert anschließend Produkttitel, Preis, Bild, Verfügbarkeit und SKU als JSON |
| `extract_article` | `url` | Single-Abruf mit Proxy-Fallback, entfernt Navigation sowie Werbung und liefert bereinigtes Artikel-JSON |
| `monitor_pricing` | `url`, optional `target_price` | Proxy-Abruf, liest aktuellen Preis aus und vergleicht ihn mit dem Zielwert |
| `check_endpoint_health` | `url`, optional `expected_text` | Single-Abruf mit strikter Validierung, liefert Erreichbarkeit und Latenz |
| `bulk_fetch_urls` | `urls` (kommagetrennt) | Paralleler Single-Abruf, automatischer Fallback auf Proxy pro URL, gibt nur Metadaten zurück |

Prompts verbrauchen im Leerlauf null Tokens. Nur aufgerufene Prompts gelangen in den LLM-Kontext.

Vollständiger Text inklusive manueller Fallback-Prompts: [MCP Recipes](https://foura.ai/docs/mcp/recipes).

## Error-Envelope

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

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

Bei Upstream-Fehlern mit HTTP-Status ist `status` ebenfalls vorhanden. Bei Rate-Limit- und Kapazitaetsfehlern enthaelt der Upstream-Envelope zusaetzlich `retryAfter`, `current.{concurrency, rpm}` und `limits.{maxConcurrency, maxRpm}`. Siehe [API-Fehler](https://foura.ai/docs/api/errors) fuer die zugrundeliegende REST-Struktur.

Stabile `code`-Werte:

| Code | HTTP | Bedeutung | Retry sicher? |
|---|---|---|---|
| `ssrf_blocked` | k. A. | Das Ziel ist eine private oder reservierte Adresse (RFC 5735, 6598, IPv6 reserviert), die URL ist nicht http(s) oder ihr Hostname konnte nicht aufgeloest werden | Nein, pruefe die URL. Ein kurzzeitig fehlgeschlagenes Lookup kann wiederholt werden |
| `upstream_non_json` | variiert | Upstream hat fehlerhaften Body zurueckgegeben | Eventuell, untersuchen |
| `output_validation_failed` | k. A. | Das `outputSchema` des MCP-Servers hat die Upstream-Antwort abgelehnt oder das Tool konnte den Aufruf gar nicht abschliessen (kein API-Key konfiguriert, API nicht erreichbar) | Eventuell: Setup pruefen, dann melden |
| `bad_request` | 400 | Eingabeformat abgelehnt, die Ziel-URL verweist auf die eigene API von FourA statt auf eine Seite (dort kann nur `/inspect` abgerufen werden) oder die URL enthaelt ein unkodiertes Leerzeichen (als `%20` kodieren) | Nein, Argumente korrigieren |
| `auth_failed` | 401 | Key fehlt, ist ungueltig oder deaktiviert | Nein, Key korrigieren |
| `forbidden` | 403 | Das Ziel hat mit 403 geantwortet und dein `validate` hat es abgelehnt (ein Site-Check, eine Laenderbeschraenkung) | Nein, oder wechsle zu `foura_proxy` |
| `not_found` | 404 | Ziel oder Endpoint fehlt | Nein |
| `rate_limited` | 429 | RPM-Limit erreicht | Ja, warte `retryAfter` |
| `at_capacity` | 503 | Concurrency-Limit erreicht oder der Dienst ist wegen Wartungsarbeiten deaktiviert (`error` lautet `Service disabled`) | Ja, warte `retryAfter` |
| `service_disabled` | 503 | Reserviert. Ein wegen Wartung deaktivierter Dienst wird aktuell als `at_capacity` ausgegeben, und ein nicht im Plan enthaltenes Tool als `plan_limit_feature` | Support kontaktieren |
| `service_unavailable` | 503 | Generischer 503 | Ja, kurzer Backoff |
| `upstream_error` | 500+ oder 0 | Das Ziel hat mit einem Serverfehler geantwortet, oder bei `foura_proxy` haben `foura_browser` und `foura_auto` nie geantwortet | Ja, exponentieller Backoff |
| `upstream_client_error` | 4xx | Sonstiger 4xx | Meistens nein |
| `upstream_unknown` | Sonstige | Der Request lief durch, lieferte aber keine akzeptierte Antwort: Bei `foura_single` hat das Ziel nie geantwortet (Timeout, Connection Refused), und bei jedem Tool hat dein `validate` eine 2xx- oder 3xx-Antwort abgelehnt. Lies `status` und `error` | Untersuchen |
| `no_eligible_proxy` | k. A. | Kein Proxy entspricht dem strikten Scope von `exitCountries` | Spaeter wiederholen; Scope nur explizit aendern |
| `plan_limit_*` | 403 oder 429 | Ein Limit deines Plans hat den Aufruf abgelehnt: `plan_limit_` gefolgt von `feature`, `premium`, `concurrency`, `rate`, `browser_daily`, `credits` oder `bandwidth`. Siehe [MCP-Server-Fehler](https://foura.ai/docs/mcp/errors) | Warte `retryAfter`, falls vorhanden; andernfalls erst nach Reset des Limits oder Plan-Aenderung |

LLM-Agents können `code` direkt für Retry-Logik auslesen, ohne Fließtext zu parsen. Authentifizierungs-Anleitung: [Authentication](https://foura.ai/docs/getting-started/authentication).

## Limits

- Standardmäßig Inline-Body. Mit `offload_large: true` werden Responses >= 50 KB auf Festplatte geschrieben + `resource_link` (pro Tenant, 1 Stunde TTL).
- Private Ziele werden auf 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 Dienst durchgesetzt. Siehe [Rate Limits](https://foura.ai/docs/api/rate-limits).

## Self-Hosting

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

Konfigurierbare Umgebungsvariablen:

| Variable | Default | Purpose |
|---|---|---|
| `PORT` | `3076` | HTTP-Listen-Port |
| `FOURA_API_BASE` | `https://api.foura.ai/api` | Upstream FourA REST Basis-URL |
| `FOURA_MCP_PAYLOADS_DIR` | ein `foura-mcp-payloads`-Ordner im temporären Systemverzeichnis (die mitgelieferte Docker-Compose-Datei setzt `/data/payloads`) | Speicherort für auf Festplatte zwischengespeicherte Responses >= 50 KB (mit `offload_large: true`) |
| `FOURA_MCP_ALLOWED_HOSTS` | `mcp.foura.ai,localhost,127.0.0.1,[::1]` | Hostname-Allowlist für den `Host`-Header (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-Aufrufer |

Der offizielle Container läuft als `uid 1001` (Non-Root). Die mitgelieferte Docker-Compose-Datei speichert `/data/payloads` auf einem Named Volume; ein Host-Bind-Mount unter diesem Pfad 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. Verweise mit `offload_large` bei `FOURA_MCP_PAYLOADS_DIR` auf einen gemeinsamen Speicher für alle Instanzen, da ein gespeicherter Payload auf der Festplatte der Instanz liegt, die ihn geschrieben hat. `GET /healthz` antwortet mit `ok`, `name` und `version`, damit ein Load Balancer eine Instanz prüfen kann.
