MCP Server

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

Быстрый старт: локальный stdio (рекомендуется для Claude Desktop)

Получите ключ на странице foura.ai/dashboard#api-keys (в один клик, показывается один раз при создании, формат pk_live_...). Добавьте его в конфигурацию вашего 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 при первом запуске (около 10 секунд) и запускает его как подпроцесс вашего 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`

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

Быстрый старт: хостинг (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 не поддерживают чистый формат url. Используйте конфигурацию stdio выше для Claude Desktop или настройте мост через mcp-remote:

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

Справочник размещенного endpoint

Свойство	Значение
URL	`https://mcp.foura.ai/mcp`
Транспорт	Streamable HTTP (POST `/mcp`, SSE-ответы)
Аутентификация	`Authorization: Bearer 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", resource_metadata="https://foura.ai/docs/mcp/server#auth"`

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

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

Инструменты

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

foura_single

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

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

foura_proxy

HTTP-request, маршрутизируемый через пул ротируемых proxy с автоматическим повтором. От 1 до 5 с. Повторяет POST /api/proxy/.

Используйте, когда foura_single возвращает 403, CAPTCHA или заблокированный по геопозиции контент. Response содержит ID успешного proxy (proxy) и общее астрономическое время выполнения в секундах (total, float).

foura_browser

Полноценная сессия браузера. Выполняется JavaScript, рендерится DOM, возвращаются cookies. От 2 до 10 с. Повторяет POST /api/browser/.

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

Структуру входных данных, значения по умолчанию и правила валидации для каждого инструмента можно найти в справочнике REST-endpoints. Схемы инструментов полностью совпадают с полями REST API, за исключением параметра offload_large, доступного только в MCP (см. ниже).

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

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

foura_single: { status, headers, data, total_time, ... } (headers представляет собой массив, по одной записи на каждый этап перенаправления)
foura_proxy: аналогично single плюс { proxy, total } (где total представляет собой секунды типа float, внешнее время выполнения, включая повторные попытки)
foura_browser: отдельная структура { status, headers: object, body, cookies, userAgent } (обратите внимание: body может быть строкой или объектом в зависимости от content-type)

Клиенты с поддержкой structuredContent (Claude Desktop, Cursor, Windsurf по состоянию на 2026 год) передают типизированный объект напрямую в LLM, минуя повторную токенизацию JSON как строки. Это позволяет экономить 30-40% токенов на типичных ответах.

Многозначные заголовки ответов

Заголовки, которые появляются несколько раз (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=/"]
    }
  ]
}

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

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

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

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

{
  "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 extension	поддерживается

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

Встроенные Prompts

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

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

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

Полный текст и резервные prompts для ручной настройки: MCP Recipes.

Структура ошибок

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

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

При ошибках вышестоящего сервиса с HTTP-статусом также присутствует поле status. При ошибках лимитов запросов и емкости вышестоящая структура добавляет поля retryAfter, current.{concurrency, rpm} и limits.{maxConcurrency, maxRpm}. См. раздел Ошибки API для ознакомления с базовой структурой REST.

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

Code	HTTP	Значение	Безопасно для повтора?
`ssrf_blocked`	n/a	Целевой IP находится в приватном или зарезервированном диапазоне (RFC 5735, 6598, зарезервированные IPv6)	Нет, измените URL
`upstream_non_json`	варьируется	Вышестоящий сервис вернул некорректное тело ответа	Возможно, изучите проблему
`output_validation_failed`	n/a	Схема `outputSchema` MCP-сервера отклонила ответ вышестоящего сервиса (ошибка сервера или неожиданная структура ответа)	Возможно, сообщите об ошибке
`bad_request`	400	Некорректная структура входных данных	Нет, исправьте аргументы
`auth_failed`	401	Ключ отсутствует, недействителен или деактивирован	Нет, исправьте ключ
`forbidden`	403	Аутентификация пройдена, но доступ запрещен	Нет, либо переключитесь на `foura_proxy`
`not_found`	404	Целевой ресурс или endpoint не найден	Нет
`rate_limited`	429	Превышен лимит запросов в минуту (RPM)	Да, подождите `retryAfter`
`at_capacity`	503	Превышен лимит параллельных запросов	Да, подождите `retryAfter`
`service_disabled`	503	Технические работы или ваш тарифный план не включает этот инструмент	Обратитесь в поддержку
`service_unavailable`	503	Общая ошибка 503	Да, с небольшой задержкой
`upstream_error`	500+	Ошибка вышестоящего сервиса 5xx	Да, с экспоненциальной задержкой
`upstream_client_error`	4xx	Другая ошибка вышестоящего сервиса 4xx	Обычно нет
`upstream_unknown`	другое	Защитный код, на практике возникать не должен	Изучите проблему

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

Лимиты

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

Self-Hosting

Каждый инстанс запускается в одном контейнере без сохранения состояния (statelessly). Публичное зеркало на GitHub появится с выходом версии v1.0. До этого момента исходный код находится в приватном репозитории, а образ контейнера предоставляется по запросу. Для получения раннего доступа свяжитесь с support@foura.ai.

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

| Переменная | По умолчанию | Назначение | |---|---| | PORT | 3076 | Порт прослушивания HTTP | | FOURA_API_BASE | https://api.foura.ai/api | Базовый URL для REST API вышестоящего FourA | | FOURA_MCP_PAYLOADS_DIR | /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 для браузерных клиентов | | FOURA_MCP_RESOURCE_METADATA_URL | https://foura.ai/docs/mcp/server#auth | URL, возвращаемый в заголовке WWW-Authenticate при ошибке 401 |

Запускается от имени uid 1001 (не root) в официальном контейнере. Точка монтирования /data/payloads на хосте должна быть доступна для записи этому uid.

Масштабируйте горизонтально за любым балансировщиком нагрузки. Клиенты передают свой ключ при каждом запросе, поэтому липкие сессии (sticky sessions) не требуются.

Обновлено: 1 июля 2026 г.

MCP Server

MCP Server

Быстрый старт: локальный stdio (рекомендуется для Claude Desktop)

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

Справочник размещенного endpoint

Инструменты

foura_single

foura_proxy

foura_browser

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

Многозначные заголовки ответов

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

Встроенные Prompts

Структура ошибок

Лимиты

Self-Hosting

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