Сервер MCP

Используйте FourA из любого клиента Model Context Protocol (Claude Desktop, Claude Code, Cursor, Windsurf, VS Code) как четыре нативных инструмента и шесть промптов для рабочих процессов. Без кода интеграции, без собственного HTTP-клиента.

Открытый исходный код на GitHub; в npm как @fouradata/mcp. Текущий релиз: 0.8.3.

Получите ключ на foura.ai/dashboard#api-keys (в один клик, формат pk_live_..., кнопка Reveal покажет ключ позже). Добавьте это в конфигурацию вашего клиента MCP:

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

Важный нюанс Claude Desktop: полностью закройте Claude Desktop (Cmd+Q на macOS) до редактирования файла конфигурации. Если приложение все еще запущено, при выходе оно перезапишет ваши изменения конфигурацией из памяти.

Команда npx скачивает @fouradata/mcp при первом запуске и запускает его как подпроцесс вашего MCP-клиента. Глобальная установка не требуется.

Клиент Где находится конфигурация
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 (сначала установите FOURA_API_KEY в переменных окружения)
Cursor ~/.cursor/mcp.json
Windsurf ~/.codeium/windsurf/mcp_config.json
VS Code (расширение MCP) .vscode/mcp.json, внутри верхнеуровневого ключа servers вместо mcpServers

Перезапустите клиент. Инструменты (foura_auto, foura_single, foura_proxy, foura_browser) и шесть prompt-шаблонов появятся в вашем списке инструментов.

Быстрый старт: хостинг (Streamable HTTP)

Для клиентов с поддержкой транспорта Streamable HTTP (Cursor, Windsurf, VS Code, Claude Code с --transport http) укажите размещенный endpoint вместо запуска локального подпроцесса:

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

Для Claude Desktop используйте конфигурацию stdio выше или пробросьте размещенный endpoint через mcp-remote:

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

Справочник по hosted endpoint

Свойство Значение
URL https://mcp.foura.ai/mcp
Транспорт Streamable HTTP (POST /mcp, SSE-ответы)
Аутентификация Authorization: Bearer pk_live_... на каждый request. Простой ключ в Authorization или X-API-Key: pk_live_... также подходит
MCP-Protocol-Version Согласно @modelcontextprotocol/sdk (в настоящее время 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05, 2024-10-07)
401 challenge WWW-Authenticate: Bearer realm="foura-mcp"

Челендж 401 намеренно не содержит параметра resource_metadata из RFC 9728. Его объявление заставляет клиент с поддержкой OAuth запускать флоу, который этот сервер не реализует. Отправьте ваш pk_live_ ключ как Bearer token, и ошибка 401 исчезнет.

Размещенный сервер не сохраняет состояние (stateless). Каждый request передает собственный ключ, который сервер перенаправляет в FourA API как X-API-Key. Один ключ открывает доступ ко всем четырем инструментам.

Для защиты от DNS-rebinding (CVE-2025-66414) сервер валидирует заголовок Host (должен быть mcp.foura.ai или localhost) и заголовок Origin при его наличии (в белом списке: mcp.foura.ai, claude.ai, app.cursor.sh, app.cursor.com). Вызовы между серверами (curl, MCP-клиенты в режиме моста stdio) не отправляют Origin и проходят без ограничений.

Инструменты

Все четыре инструмента аннотированы как readOnlyHint: true и openWorldHint: true в соответствии со спецификацией MCP 2025-06-18. Клиенты с автоматическим подтверждением доверенных read-only инструментов вызывают их без модального окна подтверждения на каждый request.

foura_auto является интеллектуальным вариантом по умолчанию: передайте ему URL, и он вернет контент, самостоятельно выбрав метод выборки. Остальные три инструмента представляют собой низкоуровневые примитивы, которыми он управляет; используйте их, когда требуется явный контроль.

foura_auto

Передайте ему URL, если требуется, чтобы FourA сама выбрала метод отправки request. Она выполняет ограниченное число попыток, используя доступные пути через HTTP, proxy и браузер. Передавайте validate для защищенных целей, чтобы response обязательно содержал контент, идентифицирующий настоящую страницу. Если ни одна попытка не проходит валидацию, инструмент возвращает ошибку вместо того, чтобы выдавать страницу с проверкой за успешный результат.

В response включаются детали завершения в meta и по умолчанию повторно используемый session с proxy, cookies и userAgent. Для простого повторного запроса вызовите foura_single со значением session.proxy в качестве proxy, сериализуйте cookie в виде заголовка Cookie и отправьте session.userAgent в заголовке User-Agent. Для рендеринга JavaScript передайте параметры сессии в соответствующие поля foura_browser.

Задайте exitClass: "premium", чтобы разрешить Auto переключаться на премиум-выход, если стандартный пул не может получить доступ к странице. Значение exitClass: "standard" и отсутствие этого поля оставляют Auto в стандартном пуле, и только request с указанием класса возвращает exitClass. Это работает так же, как в foura_proxy: это разрешение, а не жесткая инструкция; такой трафик списывается из лимита премиум-трафика вашего тарифа и отклоняется с кодом code: "plan_limit_premium" на тарифах без премиум-выходов. Поле exitClass в результате указывает, какой класс выполнил доставку. См. exitClass в Smart Fetch.

foura_single

Один HTTP-request, один response. Полностью повторяет POST /api/single/ один к одному.

Используйте для статических страниц, JSON API, HTML с серверным рендерингом.

Выбор эмулируемого браузера

По умолчанию request эмулирует последнюю версию Google Chrome. Если целевой ресурс принимает один браузер и блокирует другой, задайте browser (Chrome, Edge, Safari, Firefox или Tor), os (Windows, macOS, Android или iOS) или version, либо передайте точный идентификатор profile:

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

При совпадении нескольких профилей выбирается самая новая версия. Если комбинация не существует, возвращается ошибка со списком доступных вариантов, поэтому запрос никогда не отправляется от имени браузера, который вы не выбирали. Для выбора требуется unblocker, включенный по умолчанию. Каталог опубликован по адресу GET /api/profiles и не требует API key.

Те же четыре поля находятся внутри объекта request в foura_proxy.

foura_proxy

Маршрутизация одного HTTP request через ротируемые proxy с автоматическим повтором. Используйте его, когда foura_single заблокирован или целевой ресурс требует определенной страны выхода.

Задайте в exitCountries строгий список разрешенных двухбуквенных кодов стран, видимых целевому ресурсу, переданный пользователем или обусловленный требованиями цели:

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

Значения обрезаются по краям, переводятся в верхний регистр и дедуплицируются. Выходные узлы стандартного пула с неизвестной страной исключаются, и стандартный пул никогда не переключается на незапрошенную страну. Премиум-узел также остается в пределах списка: при exitClass: "premium" стандартный пул по-прежнему опрашивается первым, а премиум-узел выбирается из указанных вами стран и возвращает ее имя в exitCountry. Выбор использует последние доступные метаданные страны, видимые целевым ресурсом, которые обычно обновляются в течение десяти минут; это не онлайн-проверка геолокации во время запроса. Не определяйте обслуживающую страну по адресу хоста proxy.

Успешный ответ с ограничением по региону возвращает exitCountry и переиспользуемый идентификатор proxy. Убедитесь, что exitCountry входит в запрошенный список разрешенных стран. Если в текущем пуле нет совпадений, инструмент возвращает code: "no_eligible_proxy" с нормализованной областью видимости в details.exitCountries. Сохраните эту область и повторите попытку позже. Изменяйте или расширяйте ее только тогда, когда пользователь явно меняет требование. Ограничение по странам доступно начиная с тарифного плана Startup. На тарифе без этой функции вызов, отправляющий exitCountries, отклоняется с кодом 403 и ошибкой X-FourA-Limit: plan_limit_feature.

Если выбранной странице позже потребуется JavaScript, передайте возвращенный идентификатор proxy в foura_browser.proxy, чтобы браузер повторно использовал тот же выходной узел.

Задайте exitClass: "premium" для целевого ресурса, до которого стандартный пул не может добраться независимо от количества опробованных узлов. Это разрешение, а не жесткая инструкция: стандартный пул по-прежнему пытается получить ответ первым и обычно успевает, а запрос, на который он ответил до попытки использования премиум-узлов, не расходует премиум-трафик. Попытка через премиум-узел учитывает переданный трафик, даже если она завершилась ошибкой. Ответ возвращает exitClass со значением premium или standard, чтобы вы могли видеть по каждому запросу, какой класс вас обслужил. standard также возвращается, когда включенный в ваш тариф премиум-трафик исчерпан, и это штатный результат, а не ошибка. exitClass: "standard" полностью запрещает эскалацию. exitClass: "premium" на тарифе без премиум-узлов отклоняется с ошибкой code: "plan_limit_premium". См. exitClass.

Когда ротации пришлось переключиться на другой браузер для получения ответа, успешный ответ содержит profile: идентификатор профиля каталога, на котором она остановилась. Передайте его как profile в следующем вызове, чтобы использовать тот же браузер.

Неудачная ротация возвращает attemptReport рядом с ошибкой: одно предложение summary, а также счетчики, разделяющие узлы, которые так и не ответили (noResponse), узлы, отклоненные проверкой на ботов (defense, с указанием поставщиков в vendors), страницы, которые были получены, но отклонены исключительно вашим собственным validate.data (contentRejected), statusRejected и other. profilesTried перечисляет браузеры, отправленные задачей, в порядке первого использования, где default означает, что запрос ушел точно в исходном виде. Высокое значение contentRejected означает, что FourA доставил реальные страницы, а ваше собственное правило их отбросило. См. Why a Proxy Request Ran Out of Tries.

foura_browser

Полная сессия браузера. JavaScript выполняется, DOM рендерится, cookie возвращаются. Полностью повторяет POST /api/browser/.

Используйте для одностраничных приложений (SPA), контента с отложенной загрузкой или страниц с проверками, требующими настоящего браузера.

Форматы входных данных, значения по умолчанию и правила валидации для каждого инструмента см. в справочнике по REST endpoint. Схемы инструментов соответствуют REST API, плюс опция offload_large только для MCP (см. ниже), за двумя исключениями: у foura_browser нет поля lean, а у foura_proxy пока нет полей exit location. Значения, переданные под этими именами, не попадут в API. Чтобы задать их, вызывайте POST /api/browser/ или POST /api/proxy/ напрямую.

Когда целевой ресурс запускает проверку на ботов

foura_single и foura_proxy возвращают defense, если целевой ресурс выполнял проверку на ботов перед отдачей тела ответа. Значение defense.solved: true означает, что проверка пройдена и data содержит настоящую страницу; false означает, что тело может быть страницей с вызовом (challenge). Повторите запрос с другим браузером, ОС или версией, либо перейдите на foura_proxy или foura_browser, вместо того чтобы обрабатывать страницу проверки как контент.

Типизированные ответы

Каждый ответ инструмента содержит как content (удобочитаемую текстовую сводку), так и structuredContent (типизированный JSON, проверенный по outputSchema инструмента). Каждый инструмент имеет свою собственную структуру:

  • foura_auto: структура single { status, headers, data } плюс meta ({ rung, solved, attempts, credits, attemptsByEngine, browserRequests }, присутствует всегда, где rung принимает одно из значений cache, probe, proxy, browser, warmup, fail) и, по умолчанию, session ({ proxy, cookies, userAgent }) для повторного воспроизведения через низкоуровневые инструменты; запрос с указанием класса также включает exitClass. meta.attemptsByEngine считает запросы, отправленные вызовом в Single, Proxy и Browser, а meta.browserRequests считает запросы, израсходовавшие ваш дневной лимит Browser. При ошибке также возвращается attemptReport. Без total_time.
  • foura_single: { status, headers, data, total_time, ... } (headers представляет собой массив, по одной записи на каждый этап редиректа)
  • foura_proxy: то же, что и single, плюс { proxy, total }; успешный запрос со scope также включает exitCountry, запрос с указанием класса включает exitClass, ротация со сменой семейства браузера включает profile, а ошибка включает attemptReport
  • foura_browser: отдельная структура { status, headers: object, body, cookies, userAgent } (примечание: body может быть строкой или объектом в зависимости от content-type)

Каждый инструмент также сообщает стоимость вызова и данные для его трассировки, полученные из заголовков ответа API:

  • credits: списанные за этот вызов кредиты. Присутствует и при ошибках, так как работа в любом случае была выполнена. Оплата взимается только за успешный вызов, поэтому при ошибке кредиты отображаются здесь, но фактически ничего не стоят.
  • request_id: идентификатор вызова в FourA. Указывайте его при обращении в поддержку.
  • exitClass: premium, если вызов обрабатывался через premium exit. На foura_single и foura_browser это происходит, когда proxy повторно использует premium exit, найденный foura_proxy или foura_auto.

Каждое поле отсутствует, если API ничего не вернул, поэтому клиенты под более ранние версии продолжают работать без изменений. Те же значения описаны в разделе Response Headers.

Клиенты с поддержкой structuredContent могут передавать типизированный объект напрямую в LLM без необходимости парсить JSON из текста.

Заголовки ответа с несколькими значениями

Заголовки, встречающиеся несколько раз (Set-Cookie, Link, WWW-Authenticate), возвращаются в виде массивов:

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

Это важно для сайтов, которые устанавливают cookie сессии + трекинга + согласия в одном ответе (большая часть e-commerce).

Большие ответы: offload_large (по умолчанию: inline)

По умолчанию (начиная с v0.2.0), полные тела ответов возвращаются inline в structuredContent независимо от размера. Это работает во всех клиентах MCP из коробки.

Если ваш клиент поддерживает MCP resources/read И вы хотите экономить токены на больших страницах, передавайте offload_large: true для каждого вызова инструмента. Ответы размером >= 50 КБ затем записываются на диск, возвращаются как resource_link, и ваш клиент запрашивает тело только тогда, когда оно действительно необходимо. На хостинг-сервере кэшированные полезные нагрузки удаляются через 1 час. На вашем собственном экземпляре сохраненные данные автоматически не удаляются: очищайте файлы старше одного часа из каталога полезных нагрузок самостоятельно.

Выгруженный результат содержит offloaded_resource_uri и size_bytes вместо тела. Выгруженный результат также исключает defense, а также profile для foura_proxy, поэтому не используйте offload_large при вызове, который считывает эти поля.

{
  "method": "GET",
  "url": "https://en.wikipedia.org/wiki/Web_scraping",
  "offload_large": true
}
Клиент offload_large: true
Claude Desktop пока нет, оставьте значение по умолчанию false
Claude Code, Cursor, Windsurf поддерживается
Расширение VS Code MCP поддерживается

Изоляция клиентов: каждый API key получает собственное пространство имен (sha256(apiKey)[:16]). Только тот ключ, который сохранил payload, может прочитать его обратно. Попытки межклиентского чтения возвращают Payload not found без утечки информации о существовании ресурса.

Встроенные промпты

Шесть шаблонов рабочих процессов доступны через /prompts в любом MCP клиенте. Каждый принимает именованные аргументы и возвращает шаблонное сообщение пользователя, организующее вызов одного или нескольких инструментов.

Промпт Аргументы Назначение
smart_fetch url, опционально must_contain, extract Автоматическая загрузка (выбор метода, обход защиты от ботов), затем возврат или извлечение содержимого
scrape_product_page url Загрузка через браузер, затем извлечение названия товара, цены, изображения, наличия и SKU в формате JSON
extract_article url Одиночный запрос с переходом на proxy, затем удаление навигации/рекламы и возврат чистого JSON статьи
monitor_pricing url, опционально target_price Загрузка через proxy, извлечение текущей цены, сравнение с целевой
check_endpoint_health url, опционально expected_text Одиночный запрос со строгой валидацией, возврат статуса доступности и времени ответа
bulk_fetch_urls urls (через запятую) Параллельный одиночный запрос, автоматический переход на proxy для каждого URL, возврат только метаданных

В режиме ожидания промпты не расходуют токены. Только вызванные промпты попадают в контекст LLM.

Полный текст и резервные варианты промптов для ручного вызова: Рецепты MCP.

Формат ошибок

Каждая ошибка (isError: true) возвращается в структуре structuredContent. Обязательные поля для любой ошибки:

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

При ошибках апстрима с HTTP-статусом также присутствует status. При ошибках rate limit и емкости конверт апстрима добавляет retryAfter, current.{concurrency, rpm} и limits.{maxConcurrency, maxRpm}. Базовую структуру REST см. в API Errors.

Стабильные значения code:

Код HTTP Значение Безопасен ли повтор?
ssrf_blocked н/д Цель является частным или зарезервированным адресом (RFC 5735, 6598, зарезервированные IPv6), URL не использует http(s), либо имя хоста не удалось разрешить Нет, проверьте URL. Кратковременный сбой резолва можно повторить
upstream_non_json варьируется Апстрим вернул некорректное тело ответа Возможно, изучите детали
output_validation_failed н/д Параметр outputSchema сервера MCP отклонил ответ апстрима, либо инструмент вообще не смог выполнить вызов (не настроен ключ API, API недоступен) Возможно: проверьте настройки, затем сообщите об ошибке
bad_request 400 Формат входных данных отклонен, целевой URL указывает на собственный API FourA вместо страницы (там можно запрашивать только /inspect), либо URL содержит незакодированный пробел (закодируйте его как %20) Нет, исправьте аргументы
auth_failed 401 Ключ отсутствует, недействителен или деактивирован Нет, исправьте ключ
forbidden 403 Цель вернула 403, и ваш validate отклонил ответ (проверка сайта, ограничение по стране) Нет, либо переключитесь на foura_proxy
not_found 404 Цель или endpoint не найдены Нет
rate_limited 429 Достигнут лимит RPM Да, подождите retryAfter
at_capacity 503 Достигнут лимит параллельных запросов, либо сервис отключен на обслуживание (error возвращает Service disabled) Да, подождите retryAfter
service_disabled 503 Зарезервировано. Сервис, отключенный на обслуживание, сейчас возвращает at_capacity, а недоступный в тарифе инструмент возвращает plan_limit_feature Обратитесь в поддержку
service_unavailable 503 Общая ошибка 503 Да, с небольшой паузой
upstream_error 500+ или 0 Цель ответила ошибкой сервера, либо при вызове foura_proxy сервисы foura_browser и foura_auto так и не ответили Да, с экспоненциальной задержкой
upstream_client_error 4xx Другой статус 4xx Обычно нет
upstream_unknown другое Запрос выполнился, но не дал принятого ответа: в foura_single цель не ответила (таймаут, отказ в соединении), а в других инструментах ваш validate отклонил ответ 2xx или 3xx. Проверьте status и error Изучите детали
no_eligible_proxy н/д Нет прокси, соответствующего строгому exitCountries Повторите позже; меняйте область только явно
plan_limit_* 403 или 429 Один из лимитов вашего тарифа отклонил вызов: plan_limit_, а затем feature, premium, concurrency, rate, browser_daily, credits или bandwidth. См. MCP Server Errors Подождите retryAfter, если указано; иначе до сброса лимита или смены тарифа

LLM-агенты могут читать code напрямую для логики повторных попыток без парсинга текста. Руководство по аутентификации: Authentication.

Лимиты

  • Inline body по умолчанию. С offload_large: true ответы >= 50 КБ сохраняются на диск + resource_link (для каждого тенанта отдельно, TTL 1 час).
  • Приватные адреса отклоняются (RFC 5735, RFC 6598, зарезервированные блоки IPv6) на уровне MCP. Перенаправляются только публичные хосты.
  • Ограничение размера тела запроса в 256 КБ для входящих запросов /mcp (реальные полезные нагрузки MCP составляют < 4 КБ).
  • Ограничения rate limit применяются FourA API для каждого сервиса отдельно. См. Rate Limits.

Self-hosting

Полный исходный код сервера доступен публично на GitHub под @fouradata/mcp. Клонируйте репозиторий, выполните npm install, npm run build и запустите node dist/http.js для развертывания собственного инстанса. Работает stateless в одном контейнере за любым балансировщиком нагрузки.

Настраиваемые переменные окружения:

Переменная По умолчанию Назначение
PORT 3076 HTTP-порт для прослушивания
FOURA_API_BASE https://api.foura.ai/api Базовый URL вышестоящего FourA REST API
FOURA_MCP_PAYLOADS_DIR папка foura-mcp-payloads в системном временном каталоге (вложенный файл Docker Compose задает /data/payloads) Место кэширования ответов >= 50 КБ на диске (с offload_large: true)
FOURA_MCP_ALLOWED_HOSTS mcp.foura.ai,localhost,127.0.0.1,[::1] Список разрешенных хостов для заголовка Host (защита от DNS-rebinding)
FOURA_MCP_ALLOWED_ORIGINS https://mcp.foura.ai,https://claude.ai,https://app.cursor.sh,https://app.cursor.com Список разрешенных Origin для браузерных клиентов

Официальный контейнер запускается от имени uid 1001 (non-root). Вложенный файл Docker Compose сохраняет /data/payloads на именованном томе; монтирование директории с хоста (bind mount) по этому пути должно быть доступно для записи данному uid.

Масштабируйте горизонтально за любым балансировщиком нагрузки. Клиенты передают свой ключ при каждом запросе, поэтому сохранение сессий (sticky sessions) не требуется. При использовании offload_large направьте FOURA_MCP_PAYLOADS_DIR на общее для всех инстансов хранилище, поскольку сохраненная полезная нагрузка остается на диске того инстанса, который ее записал. GET /healthz возвращает ok, name и version, что позволяет балансировщику нагрузки проверять состояние инстанса.

Обновлено: 13 ноября 2026 г.