MCP-сервер
Сервер MCP
Используйте FourA из любого клиента Model Context Protocol (Claude Desktop, Claude Code, Cursor, Windsurf, VS Code) как четыре нативных инструмента и шесть промптов для рабочих процессов. Без кода интеграции, без собственного HTTP-клиента.
Открытый исходный код на GitHub; в npm как @fouradata/mcp. Текущий релиз: 0.8.3.
Быстрый старт: локальный stdio (рекомендуется для Claude Desktop)
Получите ключ на 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, а ошибка включаетattemptReportfoura_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, что позволяет балансировщику нагрузки проверять состояние инстанса.