# Serwer MCP

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

Używaj FourA z dowolnego klienta [Model Context Protocol](https://modelcontextprotocol.io) (Claude Desktop, Claude Code, Cursor, Windsurf, VS Code) w postaci czterech natywnych narzędzi i sześciu promptów workflow. Bez kodu integracyjnego, bez własnego klienta HTTP.

Open source na [GitHubie](https://github.com/fouradata/mcp); w [npm](https://www.npmjs.com/package/@fouradata/mcp) jako `@fouradata/mcp`. Aktualne wydanie: `0.8.3`.

## Szybki start: lokalne stdio (zalecane dla Claude Desktop)

Pobierz klucz na [foura.ai/dashboard#api-keys](https://foura.ai/dashboard#api-keys) (jedno kliknięcie, format `pk_live_...`, a opcja **Reveal** pozwala wyświetlić klucz ponownie w późniejszym czasie). Wklej poniższą konfigurację do swojego klienta MCP:

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

> **Wskazówka dotycząca Claude Desktop:** zamknij całkowicie Claude Desktop (`Cmd+Q` w systemie macOS) **przed** edycją pliku konfiguracyjnego. Jeśli aplikacja nadal działa, przy wyjściu nadpisze Twoje zmiany konfiguracją z pamięci RAM.

Polecenie `npx` pobiera `@fouradata/mcp` przy pierwszym uruchomieniu i uruchamia je jako podproces Twojego klienta MCP. Globalna instalacja nie jest wymagana.

| Klient | Lokalizacja konfiguracji |
|---|---|
| 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 zmiennych środowiskowych) |
| Cursor | `~/.cursor/mcp.json` |
| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
| VS Code (rozszerzenie MCP) | `.vscode/mcp.json`, pod kluczem najwyższego poziomu `servers` zamiast `mcpServers` |

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

## Szybki start: wersja hostowana (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:

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

W przypadku Claude Desktop użyj powyższej konfiguracji stdio lub przekieruj hostowany endpoint przez `mcp-remote`:

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

## Dokumentacja hostowanego endpointu

| Właściwość | Wartość |
|---|---|
| URL | `https://mcp.foura.ai/mcp` |
| Transport | Streamable HTTP (POST `/mcp`, odpowiedzi SSE) |
| Uwierzytelnianie | `Authorization: Bearer pk_live_...` na request. Sam klucz w `Authorization` lub `X-API-Key: pk_live_...` również działa |
| MCP-Protocol-Version | Zgodnie z `@modelcontextprotocol/sdk` (obecnie `2025-11-25`, `2025-06-18`, `2025-03-26`, `2024-11-05`, `2024-10-07`) |
| Challenge 401 | `WWW-Authenticate: Bearer realm="foura-mcp"` |

Challenge 401 celowo nie zawiera parametru RFC 9728 `resource_metadata`. Jego obecność sprawia, że klient obsługujący OAuth rozpoczyna przepływ, którego ten serwer nie implementuje. Wyślij swój klucz `pk_live_` jako token Bearer, a kod 401 zniknie.

Hostowany serwer jest bezstanowy. Każdy request przesyła własny klucz, który serwer przekazuje do FourA API jako `X-API-Key`. Jeden klucz odblokowuje wszystkie cztery narzędzia.

W celu ochrony przed atakami DNS-rebinding (CVE-2025-66414) serwer weryfikuje nagłówek `Host` (musi mieć wartość `mcp.foura.ai` lub localhost) oraz nagłówek `Origin`, jeśli występuje (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ą nagłówka `Origin` i przechodzą bez przeszkód.

## Narzędzia

Wszystkie cztery narzędzia są oznaczone jako `readOnlyHint: true` oraz `openWorldHint: true` zgodnie ze [specyfikacją MCP z 2025-06-18](https://modelcontextprotocol.io/specification/2025-06-18/server/tools). Klienci, którzy automatycznie zatwierdzają zaufane narzędzia tylko do odczytu, wywołują je bez okna potwierdzenia przy każdym żądaniu.

`foura_auto` to inteligentna opcja domyślna: podajesz URL, a narzędzie zwraca zawartość, dobierając metodę pobierania za Ciebie. Pozostałe trzy to niskopoziomowe elementy bazowe, którymi ono zarządza; sięgaj po nie, gdy potrzebujesz pełnej kontroli.

### foura_auto

Podaj URL, gdy chcesz, aby FourA wybrało metodę żądania. Wykonuje ono określoną liczbę prób z wykorzystaniem dostępnych ścieżek HTTP, proxy oraz przeglądarki. Przekaż `validate` w przypadku chronionych celów, aby odpowiedź musiała zawierać treść jednoznacznie wskazującą na właściwą stronę. Jeśli żadna próba nie spełni warunków walidacji, narzędzie zwróci błąd zamiast uznawać stronę z challenge za sukces.

Odpowiedź zawiera szczegóły wykonania w `meta` oraz domyślnie sesję wielokrotnego użytku `session` z wartościami `proxy`, `cookies` i `userAgent`. W przypadku standardowego kolejnego żądania wywołaj `foura_single` z `session.proxy` jako `proxy`, zserializuj pliki cookie jako nagłówek `Cookie` i wyślij `session.userAgent` jako nagłówek `User-Agent`. Do renderowania JavaScriptu przekaż wartości sesji do odpowiadających im pól `foura_browser`.

Ustaw `exitClass: "premium"`, aby pozwolić trybowi Auto na eskalację do węzła wyjściowego premium, gdy standardowa pula nie może dotrzeć do strony. `exitClass: "standard"` oraz pominięcie tego pola pozostawiają Auto w puli standardowej, a tylko request określający klasę otrzymuje w odpowiedzi `exitClass`. Działa to tak samo jak w `foura_proxy`: jako zezwolenie, a nie polecenie, rozliczane w ramach limitu ruchu premium w Twoim planie i odrzucane z kodem `code: "plan_limit_premium"` w planie bez węzłów wyjściowych premium. Pole `exitClass` w wyniku wskazuje klasę, która zrealizowała request. Zobacz [exitClass w Smart Fetch](https://foura.ai/docs/api/endpoints#exitclass-on-smart-fetch).

### foura_single

Jeden request HTTP, bezpośrednia odpowiedź. Odpowiada [`POST /api/single/`](https://foura.ai/docs/api/endpoints) w relacji jeden do jednego.

Stosuj dla stron statycznych, API JSON oraz HTML renderowanego po stronie serwera.

#### Wybór prezentowanej przeglądarki

Request domyślnie przedstawia się jako najnowsza wersja Google Chrome. Gdy cel akceptuje jedną przeglądarkę, a odrzuca inną, ustaw `browser` (Chrome, Edge, Safari, Firefox lub Tor), `os` (Windows, macOS, Android lub iOS), `version` albo przekaż dokładny identyfikator `profile`:

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

Gdy pasuje kilka profili, wybierana jest najnowsza wersja. Nieistniejąca kombinacja zwraca błąd z listą dostępnych opcji, dzięki czemu request nigdy nie zostanie wysłany jako przeglądarka, której nie wybrano. Wybór wymaga `unblocker`, który jest domyślnie włączony. Katalog jest opublikowany pod adresem [`GET /api/profiles`](https://foura.ai/docs/api/endpoints) i nie wymaga klucza API.

Te same cztery pola znajdują się w obiekcie `request` narzędzia `foura_proxy`.

### foura_proxy

Kieruj pojedynczy request HTTP przez rotujące proxy z automatycznym ponawianiem. Użyj tego, gdy `foura_single` jest zablokowany lub cel wymaga określonego kraju wyjściowego.

Ustaw `exitCountries` na ścisłą listę dozwolonych dwuliterowych kodów krajów widocznych dla celu, dostarczonych przez użytkownika lub wynikających z wymagań celu:

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

Wartosci sa przycinane, zamieniane na wielkie litery i deduplikowane. Wezly wyjsciowe puli standardowej o nieznanym kraju sa wykluczane, a pula standardowa nigdy nie przechodzi awaryjnie na niezaadany kraj. Wezel wyjsciowy premium rowniez pozostaje na liscie: przy `exitClass: "premium"` pula standardowa nadal ma pierwszenstwo, a wezel premium wychodzi z jednego z Twoich krajow i wskazuje go w `exitCountry`. Wybor korzysta z najnowszych dostepnych metadanych o kraju widocznym dla celu, aktualizowanych zwykle w ciagu dziesieciu minut; nie jest to geolokalizacja na zywo wykonywana podczas zapytania. Nie nalezy wnioskowac o kraju obslugujacym na podstawie adresu hosta proxy.

Pomyslne wykonanie ze zdefiniowanym zakresem zwraca `exitCountry` oraz identyfikator wielokrotnego uzytku `proxy`. Sprawdz, czy `exitCountry` nalezy do zadanej listy dozwolonych. Jesli biezaca pula nie zawiera dopasowania, narzedzie zwraca `code: "no_eligible_proxy"` ze znormalizowanym zakresem w `details.exitCountries`. Zachowaj ten zakres i ponow probe pozniej. Zmien go lub rozszerz tylko wtedy, gdy uzytkownik wyraznie zmieni wymagania. Okreslanie zakresu wedlug kraju jest dostepne od planu Startup wzwyz. W planie bez tej funkcji wywolanie wysylajace `exitCountries` zostaje odrzucone z kodem `403` oraz `X-FourA-Limit: plan_limit_feature`.

Jesli wybrana strona bedzie pozniej wymagac JavaScriptu, przekaz zwrocony identyfikator `proxy` do `foura_browser.proxy`, aby przegladarka uzyla ponownie tego samego wezla wyjsciowego.

Ustaw `exitClass: "premium"` dla celu, do ktorego pula standardowa nie moze dotrzec bez wzgledu na liczbe wyprobowanych wezlow wyjsciowych. Jest to zezwolenie, a nie polecenie: pula standardowa nadal rywalizuje o odpowiedz i zazwyczaj wygrywa, a zapytanie obsluzone przez nia przed podjeciem proby z wezlem premium nie zuzywa transferu premium. Proba premium zlicza przeslany ruch nawet wtedy, gdy zakonczy sie niepowodzeniem. Odpowiedz zwraca `exitClass`, `premium` lub `standard`, dzieki czemu mozesz sprawdzic przy kazdym zapytaniu, ktora klasa je obsluzyla. `standard` jest rowniez odpowiedzia po wyczerpaniu transferu premium zawartego w planie i stanowi normalny wynik, a nie blad. `exitClass: "standard"` calkowicie zabrania eskalacji. `exitClass: "premium"` w planie bez wezlow wyjsciowych premium zostaje odrzucone z kodem `code: "plan_limit_premium"`. Zobacz [exitClass](https://foura.ai/docs/api/endpoints#exitclass).

Gdy rotacja musiala przelaczyc sie na inna przegladarke, aby uzyskac odpowiedz, udana odpowiedz zawiera `profile`: identyfikator profilu katalogu, na ktorym sie zatrzymala. Przekaz go jako `profile` przy kolejnym wywolaniu, aby przedstawic te sama przegladarke.

Nieudana rotacja zawiera `attemptReport` obok bledu: jedno zdanie `summary` oraz liczniki rozdzielajace wezly wyjsciowe, ktore nigdy nie odpowiedzialy (`noResponse`), wezly wyjsciowe odrzucone przez weryfikacje bota (`defense`, z dostawcami w `vendors`), strony, ktore dotarly i zostaly odrzucone wylacznie przez Twoja regule `validate.data` (`contentRejected`), `statusRejected` oraz `other`. `profilesTried` wyszczegolnia przegladarki wyslane przez zadanie, w kolejnosci pierwszego uzycia, gdzie `default` oznacza, ze zapytanie wyszlo dokladnie w zapisanej postaci. Wysoka wartosc `contentRejected` oznacza, ze FourA dostarczylo prawdziwe strony, a Twoja wlasna regula je odrzucila. Zobacz [Why a Proxy Request Ran Out of Tries](https://foura.ai/docs/troubleshooting/proxy-attempt-report).

### foura_browser

Pełna sesja przeglądarki. JavaScript się wykonuje, DOM się renderuje, pliki cookie wracają. Odzwierciedla [`POST /api/browser/`](https://foura.ai/docs/api/endpoints).

Używaj do aplikacji SPA, treści ładowanych asynchronicznie (lazy loading) lub stron z weryfikacją wymagającą prawdziwej przeglądarki.

Formaty danych wejściowych, wartości domyślne i reguły walidacji dla każdego narzędzia znajdziesz w [dokumentacji endpointu REST](https://foura.ai/docs/api/endpoints). Schematy narzędzi odpowiadają REST API z dodatkiem opcji `offload_large` dostępnej tylko w MCP (patrz poniżej), z dwoma wyjątkami: `foura_browser` nie ma pola `lean`, a `foura_proxy` nie ma jeszcze pól [exit location](https://foura.ai/docs/api/endpoints#exit-location). Wartość przesłana pod tymi nazwami nigdy nie trafia do API. Aby ją ustawić, wywołaj bezpośrednio [`POST /api/browser/`](https://foura.ai/docs/api/endpoints) lub [`POST /api/proxy/`](https://foura.ai/docs/api/endpoints).

### Gdy cel uruchamia weryfikację antybotową

`foura_single` i `foura_proxy` zwracają `defense`, gdy cel uruchomił weryfikację bota przed zwróceniem body. `defense.solved: true` oznacza, że weryfikacja zakończyła się sukcesem i `data` to właściwa strona; `false` oznacza, że body może zawierać stronę z wyzwaniem (challenge page). Ponów próbę z inną przeglądarką, systemem operacyjnym lub wersją, albo przejdź na `foura_proxy` bądź `foura_browser`, zamiast traktować stronę z wyzwaniem jako treść docelową.

## Typowane odpowiedzi

Każda odpowiedź narzędzia zawiera zarówno `content` (czytelne dla człowieka podsumowanie tekstowe), jak i `structuredContent` (typowany JSON zweryfikowany ze schematem `outputSchema` danego narzędzia). Każde narzędzie ma swój unikalny format:

- `foura_auto`: pojedynczy format `{ status, headers, data }` oraz `meta` (`{ rung, solved, attempts, credits, attemptsByEngine, browserRequests }`, zawsze obecne, gdzie `rung` to jedno z: `cache`, `probe`, `proxy`, `browser`, `warmup`, `fail`) oraz domyślnie `session` (`{ proxy, cookies, userAgent }`) do powtórzenia przez narzędzia niższego poziomu; request ze zdefiniowaną klasą zawiera również `exitClass`. `meta.attemptsByEngine` zlicza requesty wysłane przez wywołanie do Single, Proxy i Browser, a `meta.browserRequests` zlicza te, które zużyły dzienny limit Browser. W przypadku błędu dołączane jest także `attemptReport`. Brak `total_time`.
- `foura_single`: `{ status, headers, data, total_time, ... }` (headers to tablica, po jednym wpisie na każdy przeskok przekierowania)
- `foura_proxy`: to samo co single plus `{ proxy, total }`; pomyślne wykonanie z zakresem zawiera również `exitCountry`, request z określoną klasą zawiera `exitClass`, rotacja ze zmianą rodziny przeglądarki zawiera `profile`, a błąd zawiera `attemptReport`
- `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 content-type)

Każde narzędzie raportuje również koszt wywołania i sposób jego śledzenia, odczytane z nagłówków odpowiedzi API:

- `credits`: kredyty zużyte przez to wywołanie. Obecne również w przypadku błędów, ponieważ praca i tak została wykonana. Opłata jest pobierana wyłącznie za udane wywołanie, więc błąd pokazuje tutaj zużyte kredyty, ale nic nie kosztuje.
- `request_id`: identyfikator wywołania w FourA. Podaj go w zgłoszeniu do pomocy technicznej.
- `exitClass`: `premium`, gdy wywołanie zostało obsłużone przez węzeł wyjściowy premium. W przypadku `foura_single` i `foura_browser` dzieje się tak, gdy `proxy` odtwarza węzeł premium znaleziony przez `foura_proxy` lub `foura_auto`.

Każde z nich jest nieobecne, jeśli API nic nie zgłosiło, dzięki czemu klient napisany dla wcześniejszej wersji działa dalej bez zmian. Te same wartości są opisane w sekcji [Response Headers](https://foura.ai/docs/api/response-headers).

Klienci obsługujący `structuredContent` mogą przekazać obiekt typowany bezpośrednio do LLM, zamiast wymagać parsowania JSON z tekstu.

### Nagłówki odpowiedzi o wielu wartościach

Nagłówki występujące wielokrotnie (`Set-Cookie`, `Link`, `WWW-Authenticate`) są zwracane jako tablice:

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

Ma to znaczenie dla witryn, które ustawiają pliki cookie sesji, śledzenia i zgody w jednej odpowiedzi (większość branży e-commerce).

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

Domyślnie (od wersji v0.2.0) pełne treści response są zwracane bezpośrednio w `structuredContent` niezależnie od rozmiaru. Działa to od razu w każdym kliencie MCP.

Jeśli Twój klient obsługuje MCP `resources/read` ORAZ chcesz oszczędzać tokeny na dużych stronach, przekaż `offload_large: true` przy wywołaniu narzędzia. Odpowiedzi >= 50 KB są wtedy zapisywane na dysku, zwracane jako `resource_link`, a Twój klient pobiera treść tylko wtedy, gdy rzeczywiście jej potrzebuje. Na serwerze hostowanym buforowane ładunki wygasają po 1 godzinie. Na własnej instancji nic nie usuwa zapisanych ładunków: usuwaj pliki starsze niż godzina z katalogu ładunków we własnym zakresie.

Wynik odciążony zawiera `offloaded_resource_uri` i `size_bytes` zamiast właściwej treści. Odciążony wynik pomija również `defense` oraz `profile` w `foura_proxy`, więc pomiń `offload_large` przy wywołaniu, które odczytuje te pola.

```json
{
  "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 |
| Rozszerzenie VS Code MCP | obsługiwane |

Izolacja danych (tenant isolation): każdy klucz API otrzymuje własną przestrzeń nazw (`sha256(apiKey)[:16]`). Tylko klucz, który zapisał payload, może go odczytać. Próby odczytu między tenantami zwracają `Payload not found` bez ujawniania istnienia zasobu.

## Wbudowane prompty

Sześć szablonów workflow jest dostępnych pod `/prompts` w każdym kliencie MCP. Każdy z nich przyjmuje nazwane argumenty i zwraca sformatowany komunikat użytkownika, orkiestrujący jedno lub więcej narzędzi.

| Prompt | Argumenty | Działanie |
|---|---|---|
| `smart_fetch` | `url`, opcjonalnie `must_contain`, `extract` | Automatyczne pobieranie (dobiera metodę, obsługuje ochronę przed botami), a następnie zwraca lub ekstrahuje zawartość |
| `scrape_product_page` | `url` | Pobieranie przez przeglądarkę, a następnie ekstrakcja nazwy produktu, ceny, obrazu, stanu magazynowego i SKU jako JSON |
| `extract_article` | `url` | Tryb pojedynczy z proxy jako fallbackiem, a następnie usunięcie nawigacji/reklam i zwrócenie czystego JSON z artykułem |
| `monitor_pricing` | `url`, opcjonalnie `target_price` | Pobieranie przez proxy, ekstrakcja aktualnej ceny i porównanie z ceną docelową |
| `check_endpoint_health` | `url`, opcjonalnie `expected_text` | Tryb pojedynczy ze ścisłą walidacją, zwraca dostępność oraz metryki czasu |
| `bulk_fetch_urls` | `urls` (rozdzielone przecinkami) | Równoległe żądania pojedyncze, automatyczny fallback do proxy dla każdego URL, zwraca wyłącznie metadane |

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

Pełna treść oraz ręczne prompty awaryjne: [MCP Recipes](https://foura.ai/docs/mcp/recipes).

## Struktura błędu (envelope)

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

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

Przy błędach upstream ze statusem HTTP obecne jest również pole `status`. W przypadku błędów limitów zapytań i pojemności koperta upstream dodaje `retryAfter`, `current.{concurrency, rpm}` oraz `limits.{maxConcurrency, maxRpm}`. Zobacz [API Errors](https://foura.ai/docs/api/errors), aby poznać bazową strukturę REST.

Stabilne wartości `code`:

| Kod | HTTP | Znaczenie | Bezpieczne ponowienie? |
|---|---|---|---|
| `ssrf_blocked` | nd. | Cel jest adresem prywatnym lub zarezerwowanym (RFC 5735, 6598, zarezerwowane IPv6), URL nie używa http(s) lub jego nazwa hosta nie została rozwiązana | Nie, sprawdź URL. Krótkotrwały błąd rozpoznawania nazwy można ponowić |
| `upstream_non_json` | różne | Upstream zwrócił nieprawidłowo sformatowane body | Być może, zbadaj przyczynę |
| `output_validation_failed` | nd. | Moduł `outputSchema` serwera MCP odrzucił odpowiedź upstream lub narzędzie nie mogło ukończyć wywołania (brak skonfigurowanego klucza API, API nieosiągalne) | Być może: sprawdź konfigurację, a następnie zgłoś problem |
| `bad_request` | 400 | Odrzucono format danych wejściowych, docelowy URL wskazuje na własne API FourA zamiast na stronę (można tam pobierać tylko `/inspect`) lub URL zawiera niezakodowaną spację (zakoduj ją jako `%20`) | Nie, popraw argumenty |
| `auth_failed` | 401 | Brak klucza, klucz jest nieprawidłowy lub został dezaktywowany | Nie, popraw klucz |
| `forbidden` | 403 | Cel odpowiedział statusem 403, a Twoja reguła `validate` go odrzuciła (weryfikacja witryny, blokada regionalna) | Nie, lub przełącz na `foura_proxy` |
| `not_found` | 404 | Brakujący cel lub endpoint | Nie |
| `rate_limited` | 429 | Osiągnięto limit RPM | Tak, odczekaj `retryAfter` |
| `at_capacity` | 503 | Osiągnięto limit współbieżności lub usługa została wyłączona na czas prac konserwacyjnych (`error` wskazuje na `Service disabled`) | Tak, odczekaj `retryAfter` |
| `service_disabled` | 503 | Zarezerwowane. Usługa wyłączona na czas prac konserwacyjnych zwraca obecnie `at_capacity`, a narzędzie niedostępne w Twoim planie zwraca `plan_limit_feature` | Skontaktuj się ze wsparciem |
| `service_unavailable` | 503 | Ogólny błąd 503 | Tak, krótki backoff |
| `upstream_error` | 500+ lub 0 | Cel odpowiedział błędem serwera, albo w przypadku `foura_proxy` usługi `foura_browser` i `foura_auto` nie odpowiedziały | Tak, wykładniczy backoff |
| `upstream_client_error` | 4xx | Inny błąd 4xx | Zazwyczaj nie |
| `upstream_unknown` | inne | Żądanie zostało wykonane, ale nie zwróciło zaakceptowanej odpowiedzi: w przypadku `foura_single` cel nie odpowiedział (timeout, odrzucone połączenie), a w przypadku dowolnego narzędzia reguła `validate` odrzuciła odpowiedź 2xx lub 3xx. Sprawdź `status` i `error` | Zbadaj przyczynę |
| `no_eligible_proxy` | nd. | Żadne proxy nie odpowiada ścisłemu zakresowi `exitCountries` | Ponów później; zmieniaj zakres wyłącznie jawnie |
| `plan_limit_*` | 403 lub 429 | Jeden z limitów Twojego planu odrzucił wywołanie: `plan_limit_`, a następnie `feature`, `premium`, `concurrency`, `rate`, `browser_daily`, `credits` lub `bandwidth`. Zobacz [MCP Server Errors](https://foura.ai/docs/mcp/errors) | Odczekaj `retryAfter`, jeśli jest obecny; w przeciwnym razie poczekaj na zresetowanie limitu lub zmianę planu |

Agenci LLM mogą odczytywać `code` bezpośrednio na potrzeby logiki ponawiania prób bez parsowania tekstu. Przewodnik po uwierzytelnianiu: [Authentication](https://foura.ai/docs/getting-started/authentication).

## Limity

- Domyślnie treść inline. Z `offload_large: true` odpowiedzi >= 50 KB trafiają na dysk + `resource_link` (per tenant, 1 godzina TTL).
- Prywatne cele są odrzucane (RFC 5735, RFC 6598, zarezerwowane bloki IPv6) na poziomie warstwy MCP. Przekazywane są tylko publiczne hosty.
- Limit wielkości treści żądania 256 KB dla przychodzących żądań `/mcp` (rzeczywiste ładunki MCP mają < 4 KB).
- Limity rate limit są wymuszane przez FourA API per usługa. Zobacz [Rate Limits](https://foura.ai/docs/api/rate-limits).

## Self-Hosting

Pełny kod źródłowy serwera jest publicznie dostępny w serwisie [GitHub](https://github.com/fouradata/mcp) na licencji `@fouradata/mcp`. Sklonuj repozytorium, `npm install`, `npm run build` i uruchom `node dist/http.js`, aby postawić własną instancję. Działa bezstanowo w pojedynczym kontenerze za dowolnym load balancerem.

Konfigurowalne środowisko:

| Zmienna | Wartość domyślna | Przeznaczenie |
|---|---|---|
| `PORT` | `3076` | Port nasłuchiwania HTTP |
| `FOURA_API_BASE` | `https://api.foura.ai/api` | Bazowy adres URL upstream FourA REST |
| `FOURA_MCP_PAYLOADS_DIR` | katalog `foura-mcp-payloads` w systemowym folderze temp (dołączony plik Docker Compose ustawia `/data/payloads`) | Miejsce buforowania na dysku odpowiedzi >= 50 KB (z `offload_large: true`) |
| `FOURA_MCP_ALLOWED_HOSTS` | `mcp.foura.ai,localhost,127.0.0.1,[::1]` | Biała lista nazw hostów dla nagłówka `Host` (ochrona przed DNS-rebinding) |
| `FOURA_MCP_ALLOWED_ORIGINS` | `https://mcp.foura.ai,https://claude.ai,https://app.cursor.sh,https://app.cursor.com` | Biała lista Origin dla wywołań z przeglądarki |

Oficjalny kontener działa jako `uid 1001` (non-root). Dołączony plik Docker Compose utrzymuje `/data/payloads` na nazwanym wolumenie; montowanie host bind mount w tej ścieżce musi mieć prawa zapisu dla tego UID.

Skaluj horyzontalnie za dowolnym load balancerem. Klienci przekazują swój klucz przy każdym żądaniu, więc sesje sticky session nie są wymagane. Z `offload_large` skieruj `FOURA_MCP_PAYLOADS_DIR` na pamięć współdzieloną przez wszystkie instancje, ponieważ zapisany ładunek znajduje się na dysku instancji, która go zapisała. `GET /healthz` odpowiada za pomocą `ok`, `name` oraz `version`, dzięki czemu load balancer może sprawdzać stan instancji.
