MCP-Server

Nutze FourA von jedem Model Context Protocol-Client (Claude Desktop, Claude Code, Cursor, Windsurf, VS Code) aus als drei native Tools und fünf Workflow-Prompts. Kein Integrationscode, kein benutzerdefinierter HTTP-Client.

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

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

{
  "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 In-Memory-Konfiguration.

Der npx-Befehl lädt @fouradata/mcp beim ersten Start herunter (~10s) 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 env)
Cursor	`~/.cursor/mcp.json`
Windsurf	`~/.codeium/windsurf/mcp_config.json`
VS Code (MCP-Erweiterung)	`.vscode/mcp.json`

Starte den Client neu. Die Tools (foura_single, foura_proxy, foura_browser) und fünf 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:

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

Aktuelle Claude Desktop-Builds lehnen die reine url-Form ab. Verwende die obige stdio-Konfiguration für Claude Desktop oder schalte mcp-remote dazwischen:

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

Referenz des gehosteten Endpoints

Eigenschaft	Wert
URL	`https://mcp.foura.ai/mcp`
Transport	Streamable HTTP (POST `/mcp`, SSE-Responses)
Authentifizierung	`Authorization: Bearer pk_live_...` pro Request
MCP-Protocol-Version	Laut `@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 drei Tools.

Zum Schutz vor DNS-Rebinding (CVE-2025-66414) validiert der Server den Host-Header (muss mcp.foura.ai oder localhost sein) und den Origin-Header, falls vorhanden (erlaubt: 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-Header und werden durchgelassen.

Tools

Alle drei Tools sind gemäß der MCP-Spezifikation 2025-06-18 mit readOnlyHint: true und openWorldHint: true annotiert. Clients, die vertrauenswürdige Read-only-Tools automatisch genehmigen, rufen diese ohne Bestätigungs-Modal pro Request auf.

foura_single

Ein HTTP-Request, Response zurück. 200 ms bis 2 s. Spiegelt POST /api/single/ eins zu eins wider.

Verwende dies für statische Seiten, JSON-APIs, serverseitig gerendertes HTML.

foura_proxy

HTTP-Request, geroutet über einen rotierenden Proxy-Pool mit automatischem Retry. 1 bis 5 s. Spiegelt POST /api/proxy/ wider.

Verwende dies, wenn foura_single 403, CAPTCHA oder geoblockierte Inhalte zurückgibt. Die Response enthält die erfolgreiche Proxy-ID (proxy) und die gesamte reale Laufzeit in Sekunden (total, Float).

foura_browser

Vollständige Browser-Session. JavaScript wird ausgeführt, das DOM gerendert, Cookies werden zurückgegeben. 2 bis 10 s. Spiegelt POST /api/browser/ wider.

Verwende dies für Single-Page-Apps, Lazy-Loading-Inhalte oder Seiten hinter Anti-Bot-Challenges, die einen echten Browser zur Lösung erfordern.

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

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

foura_single: { status, headers, data, total_time, ... } (headers ist ein Array, ein Eintrag pro Redirect-Hop)
foura_proxy: wie Single, plus { proxy, total } (wobei total Float-Sekunden sind, Gesamtlaufzeit inklusive Retries)
foura_browser: eigene Struktur { status, headers: object, body, cookies, userAgent } (Hinweis: body kann je nach Content-Type ein String oder ein Objekt sein)

Clients, die structuredContent unterstützen (Claude Desktop, Cursor, Windsurf ab 2026), übergeben das typisierte Objekt direkt an das LLM und überspringen die JSON-zu-String-Re-Tokenisierung. Erwarte 30-40 % Token-Ersparnis bei typischen Responses.

Mehrwertige Response-Header

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

{
  "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 einzigen Response setzen (gilt für die meisten E-Commerce-Seiten).

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 direkt ab Werk.

Wenn dein Client MCP-resources/read unterstützt UND du Token bei großen Seiten 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 erst 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, belasse Standard auf `false`
Claude Code, Cursor, Windsurf	unterstützt
VS Code MCP-Erweiterung	unterstützt

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

Integrierte Prompts

Fünf Workflow-Vorlagen erscheinen unter /prompts in jedem MCP-Client. Jede nimmt benannte Argumente entgegen und gibt eine vorlagenbasierte User-Message zurück, die ein oder mehrere Tools orchestriert.

Prompt	Argumente	Funktion
`scrape_product_page`	`url`	Browser-Abruf, extrahiert dann Produkttitel, Preis, Bild, Lagerbestand, SKU als JSON
`extract_article`	`url`	Single mit Proxy-Fallback, entfernt dann Navigation/Werbung und gibt sauberes Artikel-JSON zurück
`monitor_pricing`	`url`, optional `target_price`	Proxy-Abruf, extrahiert aktuellen Preis, vergleicht mit Zielpreis
`check_endpoint_health`	`url`, optional `expected_text`	Single mit strikter Validierung, gibt Erreichbarkeit und Timing zurück
`bulk_fetch_urls`	`urls` (kommagetrennt)	Paralleles Single, automatisches Fallback auf Proxy pro URL, gibt nur Metadaten zurück

Prompts kosten im Leerlauf keine Token. Nur aufgerufene Prompts gelangen in den LLM-Kontext.

Vollständiger Text plus manuelle Fallback-Prompts: MCP Recipes.

Error-Envelope

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

{
  "service": "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 das Upstream-Envelope retryAfter, current.{concurrency, rpm} und limits.{maxConcurrency, maxRpm} hinzu. Siehe API Errors für die zugrunde liegende REST-Struktur.

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 gab fehlerhaften Body zurück	Eventuell, untersuchen
`output_validation_failed`	n/a	Das `outputSchema` des MCP-Servers hat die Upstream-Response abgelehnt (Server-Bug oder unerwartete Upstream-Struktur)	Eventuell, melden
`bad_request`	400	Input-Struktur abgelehnt	Nein, Argumente korrigieren
`auth_failed`	401	Key fehlt, ungültig oder deaktiviert	Nein, 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, warte `retryAfter`
`at_capacity`	503	Concurrency-Limit erreicht	Ja, warte `retryAfter`
`service_disabled`	503	Wartungsfenster oder dein Tarif enthält dieses Tool nicht	Support kontaktieren
`service_unavailable`	503	Generischer 503	Ja, kurzer Backoff
`upstream_error`	500+	Upstream 5xx	Ja, exponentieller Backoff
`upstream_client_error`	4xx	Anderer 4xx	Meistens nein
`upstream_unknown`	andere	Defensiv, sollte in der Praxis nicht auftreten	Untersuchen

LLM-Agents können code direkt für die Retry-Logik auslesen, ohne Fließtext parsen zu müssen. Anleitung zur Authentifizierung: Authentication.

Limits

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

Self-Hosting

Jede Instanz läuft zustandslos in einem Container. Ein öffentlicher GitHub-Mirror erscheint mit v1.0. Bis dahin befindet sich der Quellcode in einem privaten Repository und das Container-Image ist auf Anfrage erhältlich. Kontaktiere support@foura.ai für vorzeitigen Zugang.

Konfigurierbare Umgebung:

Variable	Standard	Zweck
`PORT`	`3076`	HTTP-Listen-Port
`FOURA_API_BASE`	`https://api.foura.ai/api`	Upstream FourA REST-Basis-URL
`FOURA_MCP_PAYLOADS_DIR`	`/data/payloads`	Speicherort, an dem 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 `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
`FOURA_MCP_RESOURCE_METADATA_URL`	`https://foura.ai/docs/mcp/server#auth`	URL, die bei 401 im `WWW-Authenticate`-Header zurückgegeben wird

Läuft als uid 1001 (Non-Root) im offiziellen Container. Der /data/payloads-Host-Bind-Mount muss für diese UID beschreibbar sein.

Skaliere horizontal hinter jedem beliebigen Load-Balancer. Clients übergeben ihren Key bei jedem Request, sodass keine Sticky-Session erforderlich ist.

Aktualisiert: 1. Juli 2026

MCP-Server

MCP-Server

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

Schnellstart: gehostet (Streamable HTTP)

Referenz des gehosteten Endpoints

Tools

foura_single

foura_proxy

foura_browser

Typisierte Responses

Mehrwertige Response-Header

Große Responses: offload_large (Standard: inline)

Integrierte Prompts

Error-Envelope

Limits

Self-Hosting

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