Serwer MCP

Używaj FourA z dowolnego klienta Model Context Protocol (Claude Desktop, Claude Code, Cursor, Windsurf, VS Code) jako czterech natywnych narzędzi i sześciu promptów do workflow. Brak kodu integracyjnego, brak niestandardowego klienta HTTP.

Open source na GitHub; na npm jako @fouradata/mcp. Aktualne wydanie: 0.5.0.

Szybki start: lokalne stdio (zalecane dla Claude Desktop)

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

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

Uwaga dotycząca Claude Desktop: zamknij całkowicie Claude Desktop (Cmd+Q na macOS) przed edycją pliku konfiguracyjnego. Jeśli aplikacja jest nadal uruchomiona, podczas zamykania nadpisze Twoje zmiany konfiguracją z pamięci.

Polecenie npx pobiera @fouradata/mcp przy pierwszym uruchomieniu i uruchamia je jako podproces klienta MCP. Nie jest wymagana globalna instalacja.

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 env)
Cursor	`~/.cursor/mcp.json`
Windsurf	`~/.codeium/windsurf/mcp_config.json`
VS Code (rozszerzenie MCP)	`.vscode/mcp.json`

Zrestartuj klienta. Narzędzia (foura_auto, foura_single, foura_proxy, foura_browser) i sześć promptów pojawi się na liście narzędzi.

Szybki start: wersja hostowana (Streamable HTTP)

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

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

W przypadku Claude Desktop użyj powyższej konfiguracji stdio lub połącz hostowany endpoint przez mcp-remote:

{
  "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	Strumieniowe HTTP (POST `/mcp`, odpowiedzi SSE)
Uwierzytelnianie	`Authorization: Bearer pk_live_...` na każdy request
Wersja protokołu MCP	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 API FourA jako X-API-Key. Jeden klucz otwiera wszystkie cztery narzędzia.

W celu ochrony przed atakami DNS rebinding (CVE-2025-66414), serwer weryfikuje header Host (musi to być mcp.foura.ai lub localhost) oraz header Origin, jeśli występuje (dozwolone wartości: mcp.foura.ai, claude.ai, app.cursor.sh, app.cursor.com). Klienci typu server-to-server (curl, klienci MCP w trybie bridge stdio) nie wysyłają Origin i przechodzą bez weryfikacji.

Narzędzia

Wszystkie cztery narzędzia są oznaczone jako readOnlyHint: true oraz openWorldHint: true zgodnie z specyfikacją MCP 2025-06-18. Klienci, którzy automatycznie zatwierdzają zaufane narzędzia read-only, wywołują je bez wyświetlania okna potwierdzenia dla każdego requestu.

foura_auto to inteligentne ustawienie domyślne: podaj URL, a narzędzie zwróci treść, automatycznie dobierając metodę pobierania. Pozostałe trzy to prymitywy niższego poziomu, którymi zarządza, użyj ich, gdy potrzebujesz jawnej kontroli.

foura_auto

Podaj URL, jeśli chcesz, aby FourA wybrało metodę dla requestu. Narzędzie wykonuje ograniczoną liczbę prób przy użyciu dostępnych ścieżek HTTP, proxy oraz przeglądarki. Przekaż validate w przypadku chronionych celów, aby response musiał zawierać treść identyfikującą rzeczywistą stronę. Jeśli żadna próba nie przejdzie walidacji pomyślnie, narzędzie zwraca błąd, zamiast prezentować stronę typu challenge jako sukces.

Response zawiera szczegóły wykonania w meta oraz, domyślnie, obiekt wielokrotnego użytku session z proxy, cookies i userAgent. W przypadku zwykłego wywołania następczego, wywołaj foura_single z session.proxy jako proxy, zserializuj cookies jako header Cookie i wyślij session.userAgent jako header User-Agent. W celu renderowania JavaScript, przekaż wartości sesji do pasujących pól foura_browser.

foura_single

Jeden request HTTP, jeden response. Odzwierciedla POST /api/single/ w stosunku jeden do jednego.

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

Wybór prezentowanej przeglądarki

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

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

Gdy pasuje kilka profili, wygrywa najnowsza wersja. Nieistniejąca kombinacja zwraca błąd z listą dostępnych opcji, dlatego request nigdy nie jest wysyłany jako przeglądarka, której nie wybrano. Wybór wymaga unblocker, które jest domyślnie włączone. Katalog jest opublikowany pod GET /api/profiles i nie wymaga klucza API.

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

foura_proxy

Przekieruj jeden request HTTP przez rotujące proxy z automatycznym ponawianiem. Użyj tego, gdy foura_single jest zablokowane 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:

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

Wartości są przycinane, zamieniane na wielkie litery i deduplikowane. Proxy z nieznanymi węzłami wyjściowymi są wykluczane, a request nigdy nie przechodzi na kraj, o który nie proszono. Wybór korzysta z najnowszych dostępnych metadanych kraju widocznych dla celu, zazwyczaj aktualizowanych w ciągu dziesięciu minut; nie jest to wyszukiwanie geolokalizacji na żywo podczas requestu. Nie wnioskuj o kraju obsługującym na podstawie adresu hosta proxy.

Zakończony sukcesem request z zakresem zwraca exitCountry oraz identyfikator proxy do ponownego użycia. Sprawdź, czy exitCountry należy do żądanej allowlisty. Jeśli w obecnej puli nie ma dopasowania, narzędzie zwraca code: "no_eligible_proxy" ze znormalizowanym zakresem w details.exitCountries. Zachowaj ten zakres i ponów próbę później. Zmieniaj lub rozszerzaj go tylko wtedy, gdy użytkownik wyraźnie zmieni wymaganie.

Jeśli wybrana strona będzie później wymagać JavaScriptu, przekaż zwrócony ID proxy do foura_browser.proxy, aby przeglądarka użyła tego samego wyjścia.

foura_browser

Pełna sesja przeglądarki. JavaScript jest uruchamiany, DOM jest renderowany, a cookie wracają. Odzwierciedla POST /api/browser/.

Używaj do aplikacji single-page, leniwie ładowanej treści lub stron za zabezpieczeniami anti-bot, które wymagają prawdziwej przeglądarki do rozwiązania.

Informacje o strukturach wejściowych, wartościach domyślnych i regułach walidacji dla każdego narzędzia znajdziesz w dokumentacji endpointów REST. Schematy narzędzi odpowiadają API REST pole po polu, z dodatkiem opcji offload_large dostępnej tylko dla MCP (zobacz poniżej).

Gdy cel uruchamia weryfikację bota

foura_single oraz foura_proxy zwracają defense, gdy cel wykonał weryfikację bota w drodze do body. defense.solved: true oznacza, że weryfikacja przebiegła pomyślnie, a data to prawdziwa strona; false oznacza, że body może być stroną wyzwania. Ponów próbę z inną przeglądarką, systemem operacyjnym lub wersją, albo przejdź na foura_proxy lub foura_browser, zamiast traktować stronę wyzwania jako treść.

Typowane response

Każdy response narzędzia zawiera zarówno content (czytelne dla człowieka podsumowanie tekstowe), jak i structuredContent (typowany JSON zweryfikowany ze schematem outputSchema narzędzia). Każde narzędzie ma swoją unikalną strukturę:

foura_auto: pojedyncza struktura { status, headers, data } plus meta ({ rung, solved, attempts, credits }, zawsze obecne, gdzie rung to jedno z cache, probe, proxy, browser, fail) oraz domyślnie session ({ proxy, cookies, userAgent }) do powtórzenia przez narzędzia niższego poziomu. Brak total_time.
foura_single: { status, headers, data, total_time, ... } (header to tablica, jeden wpis na każdy przeskok przekierowania)
foura_proxy: to samo co single plus { proxy, total }; sukces zakresowy obejmuje również exitCountry
foura_browser: odrębna struktura { status, headers: object, body, cookies, userAgent } (uwaga: body może być ciągiem znaków lub obiektem w zależności od content-type)

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

Wielowartościowe header w response

Header, które pojawiają się wielokrotnie (Set-Cookie, Link, WWW-Authenticate) wracają 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 dla witryn, które ustawiają cookie sesyjne, śledzące i dotyczące zgody w jednym response (większość e-commerce).

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

Domyślnie (od wersji 0.2.0), pełne ciała response są zwracane jako inline w structuredContent niezależnie od rozmiaru. Działa to w każdym kliencie MCP od ręki.

Jeśli twój klient obsługuje MCP resources/read ORAZ chcesz zaoszczędzić token na dużych stronach, przekaż offload_large: true przy każdym wywołaniu narzędzia. Response >= 50 KB są wtedy zapisywane na dysku, zwracane jako resource_link, a twój klient pobiera ciało tylko wtedy, gdy faktycznie go potrzebuje. Zbuforowane 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
Rozszerzenie VS Code MCP	obsługiwane

Izolacja dzierżawców: każdy klucz API otrzymuje własną przestrzeń nazw (sha256(apiKey)[:16]). Tylko klucz, który zapisał dane, może je odczytać. Odczyty między dzierżawcami zwracają Payload not found bez wycieku informacji o istnieniu.

Wbudowane Prompty

Sześć szablonów przepływu pracy pojawia się jako /prompts w każdym kliencie MCP. Każdy przyjmuje nazwane argumenty i zwraca ustandaryzowaną wiadomość użytkownika koordynującą jedno lub więcej narzędzi.

Prompt	Argumenty	Działanie
`smart_fetch`	`url`, opcjonalnie `must_contain`, `extract`	Automatyczne pobieranie (wybiera metodę, obsługuje ochronę przed botami), następnie zwraca lub wyodrębnia zawartość
`scrape_product_page`	`url`	Pobieranie w przeglądarce, następnie wyodrębnienie tytułu produktu, ceny, obrazu, zapasu, SKU w formacie JSON
`extract_article`	`url`	Tryb pojedynczy z zastępczym proxy, następnie usunięcie nawigacji/reklam i zwrócenie czystego artykułu JSON
`monitor_pricing`	`url`, opcjonalnie `target_price`	Pobranie proxy, wyodrębnienie obecnej ceny, porównanie z docelową
`check_endpoint_health`	`url`, opcjonalnie `expected_text`	Tryb pojedynczy ze ścisłą walidacją, zwrócenie osiągalności i czasu
`bulk_fetch_urls`	`urls` (oddzielone przecinkami)	Równoległy tryb pojedynczy, automatyczne zastępcze proxy dla każdego URL, zwrócenie tylko metadanych

Nieużywane prompty kosztują zero tokenów. Tylko wywołane prompty wchodzą do kontekstu LLM.

Pełny tekst i ręczne prompty zastępcze: MCP Recipes.

Opakowanie błędu

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

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

W przypadku błędów upstream ze statusem HTTP obecne jest również status. W przypadku błędów rate-limit i błędów pojemności do koperty upstream dodawane są retryAfter, current.{concurrency, rpm} i limits.{maxConcurrency, maxRpm}. Kształt REST znajduje się w Błędy API.

Stabilne wartości code:

Kod	HTTP	Znaczenie	Bezpieczne ponowienie?
`ssrf_blocked`	brak	Docelowy adres IP w zakresie prywatnym lub zarezerwowanym (RFC 5735, 6598, IPv6 zarezerwowane)	Nie, zmień URL
`upstream_non_json`	zależy	Upstream zwrócił zniekształcone ciało	Może, zbadaj
`output_validation_failed`	brak	`outputSchema` serwera MCP odrzuciło odpowiedź upstream (błąd serwera lub nieoczekiwany kształt upstream)	Może, zgłoś
`bad_request`	400	Odrzucono kształt wejścia	Nie, popraw argumenty
`auth_failed`	401	Brak klucza, klucz nieważny lub zdezaktywowany	Nie, popraw klucz
`forbidden`	403	Uwierzytelniono, ale nie zezwolono	Nie, lub przełącz na `foura_proxy`
`not_found`	404	Brak celu lub endpointu	Nie
`rate_limited`	429	Osiągnięto limit RPM	Tak, poczekaj `retryAfter`
`at_capacity`	503	Osiągnięto limit współbieżności	Tak, poczekaj `retryAfter`
`service_disabled`	503	Okno konserwacyjne lub twój plan nie obejmuje tego narzędzia	Skontaktuj się z obsługą klienta
`service_unavailable`	503	Ogólne 503	Tak, krótkie opóźnienie
`upstream_error`	500+	Upstream 5xx	Tak, wykładnicze opóźnienie
`upstream_client_error`	4xx	Inne 4xx	Zazwyczaj nie
`upstream_unknown`	inne	Defensywne, w praktyce nie powinno wystąpić	Zbadaj
`no_eligible_proxy`	brak	Żaden proxy nie pasuje do ścisłego zakresu `exitCountries`	Ponów później; zmieniaj zakres tylko jawnie

Agenci LLM mogą bezpośrednio odczytywać code w celu logiki ponawiania bez parsowania tekstu. Instrukcja uwierzytelniania: Uwierzytelnianie.

Limity

Domyślnie wstawione ciało. Przy offload_large: true, odpowiedzi >= 50 KB trafiają na dysk + resource_link (na dzierżawcę, 1 godzina TTL).
Prywatne cele są odrzucane (RFC 5735, RFC 6598, bloki zarezerwowane IPv6) w warstwie MCP. Forwardowane są tylko publiczne hosty.
Limit ciała żądania wynosi 256 KB dla przychodzących żądań /mcp (prawdziwe payloady MCP to < 4 KB).
Limity zapytań (rate limits) są egzekwowane przez API FourA per usługa. Zobacz Limity Zapytań.

Self-Hosting

Pełny kod źródłowy serwera jest publicznie dostępny w GitHub na licencji @fouradata/mcp. Sklonuj repozytorium, npm install, npm run build i uruchom node dist/http.js, aby postawić własną instancję. Działa w trybie stateless w pojedynczym kontenerze za dowolnym load balancerem.

Konfigurowalne środowisko:

Zmienna	Wartość domyślna	Cel
`PORT`	`3076`	Port nasłuchu HTTP
`FOURA_API_BASE`	`https://api.foura.ai/api`	Bazowy URL nadrzędnego API REST FourA
`FOURA_MCP_PAYLOADS_DIR`	`/data/payloads`	Gdzie odpowiedzi >= 50 KB są zapisywane w pamięci podręcznej na dysku (z `offload_large: true`)
`FOURA_MCP_ALLOWED_HOSTS`	`mcp.foura.ai,localhost,127.0.0.1,[::1]`	Lista dozwolonych 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`	Lista dozwolonych Origin dla wywołań z przeglądarki
`FOURA_MCP_RESOURCE_METADATA_URL`	`https://foura.ai/docs/mcp/server#auth`	URL zwracany w `WWW-Authenticate` przy błędzie 401

Oficjalny kontener działa jako uid 1001 (nie jako root). Podmontowany katalog hosta /data/payloads musi mieć uprawnienia do zapisu dla tego uid.

Skaluj poziomo za dowolnym load balancerem. Klienci przekazują swój klucz w każdym żądaniu, więc nie ma trwałych sesji (sticky sessions).

Aktualizacja: 6 sierpnia 2026

Serwer MCP

Serwer MCP

Szybki start: lokalne stdio (zalecane dla Claude Desktop)

Szybki start: wersja hostowana (Streamable HTTP)

Dokumentacja hostowanego endpointu

Narzędzia

foura_auto

foura_single

Wybór prezentowanej przeglądarki

foura_proxy

foura_browser

Gdy cel uruchamia weryfikację bota

Typowane response

Wielowartościowe header w response

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

Wbudowane Prompty

Opakowanie błędu

Limity

Self-Hosting

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