Serwer MCP

Używaj FourA w dowolnym kliencie Model Context Protocol (Claude Desktop, Claude Code, Cursor, Windsurf, VS Code) jako trzech natywnych narzędzi i pięciu promptów przepływu pracy. Bez kodu integracyjnego, bez własnego klienta HTTP.

Szybki start: lokalne stdio (zalecane dla Claude Desktop)

Pobierz klucz na stronie foura.ai/dashboard#api-keys (jedno kliknięcie, widoczny tylko raz przy tworzeniu, format pk_live_...). Wklej go do konfiguracji swojego klienta MCP:

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

Haczyk w Claude Desktop: wyłącz całkowicie Claude Desktop (Cmd+Q na macOS) przed edycją pliku konfiguracyjnego. Jeśli aplikacja nadal działa, przy wyjściu nadpisze Twoje zmiany swoją konfiguracją z pamięci.

Polecenie npx pobiera @fouradata/mcp przy pierwszym uruchomieniu (~10 s) i uruchamia go jako podproces klienta MCP. Globalna instalacja nie jest wymagana.

Klient	Gdzie znajduje się konfiguracja
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` (najpierw ustaw `FOURA_API_KEY` w env)
Cursor	`~/.cursor/mcp.json`
Windsurf	`~/.codeium/windsurf/mcp_config.json`
VS Code (rozszerzenie MCP)	`.vscode/mcp.json`

Uruchom ponownie klienta. Narzędzia (foura_single, foura_proxy, foura_browser) oraz pięć promptów pojawią się na Twojej liście narzędzi.

Szybki start: hostowany (Streamable HTTP)

W przypadku klientów obsługujących transport Streamable HTTP (Cursor, Windsurf, VS Code, Claude Code z --transport http), skieruj je na hostowany endpoint zamiast uruchamiać lokalny podproces:

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

Obecne wersje Claude Desktop odrzucają samą formę url. Użyj powyższej konfiguracji stdio dla Claude Desktop lub prześlij ruch przez mcp-remote:

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

Specyfikacja hostowanego endpointu

Właściwość	Wartość
URL	`https://mcp.foura.ai/mcp`
Transport	Streamable HTTP (POST `/mcp`, responses SSE)
Uwierzytelnianie	`Authorization: Bearer pk_live_...` na request
MCP-Protocol-Version	Zgodnie z `@modelcontextprotocol/sdk` (obecnie `2025-11-25`, `2025-06-18`, `2025-03-26`, `2024-11-05`, `2024-10-07`)
Wyzwanie 401	`WWW-Authenticate: Bearer realm="foura-mcp", resource_metadata="https://foura.ai/docs/mcp/server#auth"`

Hostowany serwer jest bezstanowy. Każdy request zawiera własny klucz, który serwer przekazuje do FourA API jako X-API-Key. Jeden klucz otwiera wszystkie trzy narzędzia.

W ramach ochrony przed DNS-rebinding (CVE-2025-66414) serwer weryfikuje header Host (musi to być mcp.foura.ai lub localhost) oraz header Origin, jeśli jest obecny (dozwolone: mcp.foura.ai, claude.ai, app.cursor.sh, app.cursor.com). Wywołania server-to-server (curl, klienci MCP w trybie mostka stdio) nie wysyłają headera Origin i przechodzą bez przeszkód.

Narzędzia

Wszystkie trzy narzędzia mają adnotacje readOnlyHint: true oraz openWorldHint: true zgodnie ze specyfikacją MCP 2025-06-18. Klienci, którzy automatycznie zatwierdzają zaufane narzędzia tylko do odczytu, wywołują je bez okna potwierdzenia przy każdym requeście.

foura_single

Jeden request HTTP, response zwrotny. Od 200 ms do 2 s. Odzwierciedla POST /api/single/ jeden do jednego.

Używaj do stron statycznych, API JSON, HTML renderowanego po stronie serwera.

foura_proxy

Request HTTP kierowany przez rotacyjną pulę proxy z automatycznym ponawianiem. Od 1 do 5 s. Odzwierciedla POST /api/proxy/.

Używaj, gdy foura_single zwraca 403, captcha lub treści z blokadą geograficzną. Response zawiera identyfikator proxy, które zadziałało (proxy), oraz całkowity czas rzeczywisty w sekundach (total, float).

foura_browser

Pełna sesja przeglądarki. Uruchamia się JavaScript, renderuje się DOM, wracają cookies. Od 2 do 10 s. Odzwierciedla POST /api/browser/.

Używaj do aplikacji typu single-page app, treści ładowanych leniwie (lazy-loaded) lub stron zabezpieczonych systemami antybotowymi, które wymagają prawdziwej przeglądarki do przejścia.

Strukturę wejściową, domyślne wartości i reguły walidacji dla każdego narzędzia znajdziesz w dokumentacji endpointów REST. Schematy narzędzi odpowiadają API REST pole do pola, plus opcjonalny parametr offload_large dostępny tylko w MCP (patrz poniżej).

Typowane odpowiedzi

Każdy response narzędzia zawiera zarówno content (czytelne dla człowieka podsumowanie tekstowe), jak i structuredContent (typowany JSON zweryfikowany pod kątem outputSchema narzędzia). Każde narzędzie ma swój unikalny format:

foura_single: { status, headers, data, total_time, ... } (headers to tablica, jeden wpis na każdy krok przekierowania)
foura_proxy: tak samo jak single plus { proxy, total } (gdzie total to sekundy jako float, całkowity czas uwzględniający ponowne próby)
foura_browser: odrębny format { status, headers: object, body, cookies, userAgent } (uwaga: body może być ciągiem znaków lub obiektem w zależności od typu zawartości)

Klienci obsługujący structuredContent (Claude Desktop, Cursor, Windsurf od roku 2026) przekazują typowany obiekt bezpośrednio do LLM, pomijając ponowną tokenizację JSON-a jako ciągu znaków. Możesz spodziewać się 30-40% oszczędności tokenów przy typowych responses.

Wielowartościowe nagłówki odpowiedzi

Headers, które pojawiają się wielokrotnie (Set-Cookie, Link, WWW-Authenticate), są zwracane jako tablice:

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

Ma to znaczenie w przypadku witryn, które ustawiają cookies sesji, śledzenia i zgód w jednym response (większość e-commerce).

Duże odpowiedzi: `offload_large` (domyślnie: inline)

Domyślnie (od wersji v0.2.0) pełne body responses są zwracane inline w structuredContent bez względu na rozmiar. Działa to od razu w każdym kliencie MCP.

Jeśli Twój klient obsługuje MCP resources/read ORAZ chcesz zaoszczędzić tokeny na dużych stronach, przekaż offload_large: true przy wywołaniu narzędzia. Responses ≥ 50 KB są wtedy zapisywane na dysku, zwracane jako resource_link, a Twój klient pobiera body tylko wtedy, gdy faktycznie go potrzebuje. Zapisane w pamięci podręcznej dane wygasają po 1 godzinie.

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

Klient	`offload_large: true`
Claude Desktop	jeszcze nie, pozostaw domyślne `false`
Claude Code, Cursor, Windsurf	obsługiwane
VS Code rozszerzenie MCP	obsługiwane

Izolacja na poziomie tenanta: każdy klucz API otrzymuje własną przestrzeń nazw (sha256(apiKey)[:16]). Tylko klucz, który zapisał dane, może je odczytać. Próby odczytu między tenantami zwracają Payload not found bez ujawniania informacji o istnieniu danych.

Wbudowane prompty

Pięć szablonów przepływu pracy pojawia się w sekcji /prompts w dowolnym kliencie MCP. Każdy z nich przyjmuje nazwane argumenty i zwraca szablonową wiadomość użytkownika, która zarządza jednym lub kilkoma narzędziami.

Prompt	Argumenty	Co robi
`scrape_product_page`	`url`	Pobranie przez przeglądarkę, a następnie wyodrębnienie tytułu produktu, ceny, zdjęcia, stanu magazynowego i SKU jako JSON
`extract_article`	`url`	Pobranie przez single z fallbackiem na proxy, a następnie usunięcie nawigacji/reklam i zwrócenie czystego JSON-a z artykułem
`monitor_pricing`	`url`, opcjonalnie `target_price`	Pobranie przez proxy, wyodrębnienie aktualnej ceny, porównanie z ceną docelową
`check_endpoint_health`	`url`, opcjonalnie `expected_text`	Pobranie przez single z rygorystyczną walidacją, zwrócenie dostępności i czasu odpowiedzi
`bulk_fetch_urls`	`urls` (rozdzielone przecinkami)	Równoległe pobieranie przez single, automatyczny fallback na proxy dla każdego URL, zwraca tylko metadane

Prompty nie zużywają tokenów w stanie bezczynności. Tylko wywołane prompty trafiają do kontekstu LLM.

Pełny tekst oraz ręczne prompty awaryjne (fallback): MCP Recipes.

Format błędu

Każdy błąd (isError: true) zawiera strukturę structuredContent. Minimalne pola dla każdego błędu:

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

W przypadku błędów upstream ze statusem HTTP, obecne jest również pole status. Przy błędach rate limit i wydajnościowych, struktura upstream dodaje pola retryAfter, current.{concurrency, rpm} oraz limits.{maxConcurrency, maxRpm}. Zobacz API Errors, aby poznać bazową strukturę REST.

Stabilne wartości code:

| Kod | HTTP | Znaczenie | Bezpieczne ponowienie? | |---|---| | ssrf_blocked | n/a | Docelowy adres IP znajduje się w prywatnym lub zarezerwowanym zakresie (RFC 5735, 6598, zarezerwowane IPv6) | Nie, zmień URL | | upstream_non_json | różne | Upstream zwrócił nieprawidłowe body | Może, zbadaj sprawę | | output_validation_failed | n/a | Schemat outputSchema serwera MCP odrzucił response z upstreamu (błąd serwera lub nieoczekiwana struktura upstream) | Może, zgłoś błąd | | bad_request | 400 | Odrzucono strukturę wejściową | Nie, popraw argumenty | | auth_failed | 401 | Brak klucza, jest nieprawidłowy lub został dezaktywowany | Nie, popraw klucz | | forbidden | 403 | Uwierzytelniono, ale brak uprawnień | Nie, lub przełącz się na foura_proxy | | not_found | 404 | Brak celu lub endpointu | Nie | | rate_limited | 429 | Osiągnięto limit RPM | Tak, odczekaj retryAfter | | at_capacity | 503 | Osiągnięto limit współbieżności | Tak, odczekaj retryAfter | | service_disabled | 503 | Przerwa techniczna lub Twój plan nie obejmuje tego narzędzia | Skontaktuj się ze wsparciem | | service_unavailable | 503 | Ogólny błąd 503 | Tak, krótki backoff | | upstream_error | 500+ | Błąd 5xx z upstreamu | Tak, wykładniczy backoff | | upstream_client_error | 4xx | Inny błąd 4xx | Zazwyczaj nie | | upstream_unknown | inne | Zabezpieczenie, nie powinno występować w praktyce | Zbadaj sprawę |

Agenci LLM mogą odczytywać code bezpośrednio na potrzeby logiki ponawiania prób, bez konieczności analizowania tekstu. Przewodnik po uwierzytelnianiu: Authentication.

Limity

Domyślnie body inline. Przy offload_large: true responses ≥ 50 KB trafiają na dysk + resource_link (na poziomie tenanta, TTL 1 godzina).
Prywatne cele są odrzucane (RFC 5735, RFC 6598, bloki zarezerwowane IPv6) na warstwie MCP. Przekazywane są wyłącznie publiczne hosty.
Limit rozmiaru body requestu wynosi 256 KB dla przychodzących requestów /mcp (rzeczywiste dane MCP mają < 4 KB).
Limity rate limit są wymuszane przez FourA API dla każdej usługi. Zobacz Rate Limits.

Self-Hosting

Każda instancja działa bezstanowo w jednym kontenerze. Publiczne repozytorium na GitHubie pojawi się wraz z wersją v1.0. Do tego czasu kod źródłowy znajduje się w prywatnym repozytorium, a obraz kontenera jest dostępny na żądanie. Skontaktuj się z support@foura.ai, aby uzyskać wczesny dostęp.

Konfigurowalne środowisko:

| Zmienna | Domyślnie | Przeznaczenie | |---|---| | PORT | 3076 | Port nasłuchiwania HTTP | | FOURA_API_BASE | https://api.foura.ai/api | Bazowy URL REST dla upstreamu FourA | | FOURA_MCP_PAYLOADS_DIR | /data/payloads | Miejsce zapisu responses ≥ 50 KB na dysku (przy offload_large: true) | | FOURA_MCP_ALLOWED_HOSTS | mcp.foura.ai,localhost,127.0.0.1,[::1] | Lista dozwolonych nazw hostów dla headera Host (ochrona przed DNS-rebinding) | | FOURA_MCP_ALLOWED_ORIGINS | https://mcp.foura.ai,https://claude.ai,https://app.cursor.sh,https://app.cursor.com | Lista dozwolonych źródeł (Origin) dla wywołań z przeglądarki | | FOURA_MCP_RESOURCE_METADATA_URL | https://foura.ai/docs/mcp/server#auth | URL zwracany w headerze WWW-Authenticate przy błędzie 401 |

Działa jako uid 1001 (non-root) w oficjalnym kontenerze. Podmontowany katalog hosta /data/payloads musi być zapisywalny dla tego uid.

Skaluj poziomo za dowolnym load balancerem. Klienci przekazują swój klucz w każdym requeście, więc nie ma potrzeby stosowania sticky session.

Aktualizacja: 1 lipca 2026

Serwer MCP

Serwer MCP

Szybki start: lokalne stdio (zalecane dla Claude Desktop)

Szybki start: hostowany (Streamable HTTP)

Specyfikacja hostowanego endpointu

Narzędzia

foura_single

foura_proxy

foura_browser

Typowane odpowiedzi

Wielowartościowe nagłówki odpowiedzi

Duże odpowiedzi: offload_large (domyślnie: inline)

Wbudowane prompty

Format błędu

Limity

Self-Hosting

Duże odpowiedzi: `offload_large` (domyślnie: inline)