Docs › MCP Справка › MCP Server

MCP Server

MCP Server

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

Quick Start: локален 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 при първото стартиране (~10s) и го изпълнява като подпроцес на вашия 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 в env)
Cursor ~/.cursor/mcp.json
Windsurf ~/.codeium/windsurf/mcp_config.json
VS Code (MCP разширение) .vscode/mcp.json

Рестартирайте клиента. Инструментите (foura_single, foura_proxy, foura_browser) и петте prompts ще се появят във вашия списък с инструменти.

Quick Start: хостван (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 responses)
Authentication Authorization: Bearer pk_live_... за всяка request
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), сървърът валидира Host header (трябва да бъде mcp.foura.ai или localhost) и Origin header, когато е наличен (разрешени: mcp.foura.ai, claude.ai, app.cursor.sh, app.cursor.com). Потребителите от тип сървър-към-сървър (curl, MCP клиенти в stdio bridge режим) не изпращат Origin и преминават директно.

Инструменти

И трите инструмента са анотирани с readOnlyHint: true и openWorldHint: true съгласно MCP 2025-06-18 spec. Клиентите, които автоматично одобряват доверени инструменти само за четене (read-only), ги извикват без прозорец за потвърждение за всяка request.

foura_single

Една HTTP request, response обратно. 200ms до 2s. Съответства напълно (one-to-one) на POST /api/single/.

Използвайте за статични страници, JSON APIs, server-rendered HTML.

foura_proxy

HTTP request, рутирана през пул от ротиращи proxy сървъри с автоматичен повторен опит. 1 до 5s. Съответства на POST /api/proxy/.

Използвайте, когато foura_single върне 403, captcha или гео-блокирано съдържание. Върнатият response включва proxy ID-то, което е усерило (proxy), и общото реално време в секунди (total, float).

foura_browser

Пълна браузърна сесия. Изпълнява се JavaScript, рендерира се DOM, връщат се cookies. 2 до 10s. Съответства на POST /api/browser/.

Използвайте за single-page приложения, lazy-loaded съдържание или страници зад защити срещу ботове (anti-bot), които изискват реален браузър за преминаване.

За входящите структури, стойностите по подразбиране и правилата за валидация на всеки инструмент, вижте REST endpoint reference. Схемите на инструментите съвпадат напълно с REST API поле по поле, плюс опцията offload_large, налична само за MCP (вижте по-долу).

Типизирани responses

Всеки tool 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 може да бъде string или обект в зависимост от content-type)

Клиентите, които поддържат structuredContent (Claude Desktop, Cursor, Windsurf от 2026 г.), подават типизирания обект директно към LLM, избягвайки повторното токенизиране на JSON като string. Очаквайте 30-40% спестяване на tokens при типичните responses.

Multi-value response headers

Headers, които се появяват няколко пъти (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 + cookies за проследяване + cookies за съгласие в един response (повечето сайтове за електронна търговия).

Големи responses: offload_large (по подразбиране: inline)

По подразбиране (от v0.2.0 насам), пълните тела на responses се връщат inline в structuredContent независимо от размера им. Това работи във всеки MCP клиент директно.

Ако вашият клиент поддържа MCP resources/read И искате да спестите tokens при големи страници, подайте offload_large: true при всяко извикване на инструмент. Тогава responses ≥ 50 KB се записват на диска, връщат се като 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 разширение поддържа се

Tenant-isolated: всеки API key получава собствено пространство от имена (sha256(apiKey)[:16]). Само ключът, който е съхранил данните, може да ги прочете обратно. Опитите за четене между различни tenants връщат Payload not found без изтичане на информация за съществуването им.

Вградени Prompts

Пет шаблона за работни процеси се появяват под /prompts във всеки MCP клиент. Всеки от тях приема именовани аргументи и връща шаблонизирано потребителско съобщение, оркестриращо един или повече инструменти.

Prompt Аргументи Какво прави
scrape_product_page url Извличане чрез браузър, след което извличане на заглавие на продукт, цена, изображение, наличност, SKU като JSON
extract_article url Single с резервен вариант (fallback) към proxy, след което премахване на навигация/реклами и връщане на чист JSON на статията
monitor_pricing url, опционално target_price Извличане чрез proxy, извличане на текуща цена, сравнение с целевата
check_endpoint_health url, опционално expected_text Single със строга валидация, връщане на достъпност и време за реакция
bulk_fetch_urls urls (разделени със запетая) Паралелен single, автоматичен fallback към proxy за всеки URL, връщане само на метаданни

Prompts не консумират tokens, когато не се използват. Само извиканите prompts влизат в контекста на LLM.

Пълен текст плюс ръчни fallback prompts: MCP Recipes.

Структура на грешките (Error envelope)

Всяка грешка (isError: true) носи structuredContent обвивка. Минималните полета за всяка грешка са:

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

При грешки от страна на upstream сървъра с HTTP статус, status също присъства. При грешки за rate limit и капацитет, upstream обвивката добавя retryAfter, current.{concurrency, rpm} и limits.{maxConcurrency, maxRpm}. Вижте API Errors за базовата REST структура.

Стабилни стойности на code:

| Code | HTTP | Значение | Безопасно за повторен опит? |

--- ---
ssrf_blocked n/a
upstream_non_json варира
output_validation_failed n/a
bad_request 400
auth_failed 401
forbidden 403
not_found 404
rate_limited 429
at_capacity 503
service_disabled 503
service_unavailable 503
upstream_error 500+
upstream_client_error 4xx
upstream_unknown друго

LLM агентите могат да четат code директно за логика на повторен опит, без да анализират свободен текст. Ръководство за автентификация: Authentication.

Лимити

  • Inline body по подразбиране. При offload_large: true, responses ≥ 50 KB отиват на диска + resource_link (за всеки tenant, 1 час TTL).
  • Частните цели се отхвърлят (RFC 5735, RFC 6598, IPv6 reserved блокове) на MCP ниво. Препращат се само публични хостове.
  • Лимит на тялото на request от 256 KB за входящи /mcp requests (реалните MCP payloads са < 4 KB).
  • Rate limits се налагат от FourA API за всяка услуга. Вижте Rate Limits.

Self-Hosting

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

Конфигурируема среда:

Променлива По подразбиране Предназначение
PORT 3076 HTTP listen port
FOURA_API_BASE https://api.foura.ai/api Upstream FourA REST base URL
FOURA_MCP_PAYLOADS_DIR /data/payloads Къде се кешират на диска responses ≥ 50 KB (при offload_large: true)
FOURA_MCP_ALLOWED_HOSTS mcp.foura.ai,localhost,127.0.0.1,[::1] Списък с разрешени хостове за Host header (защита срещу DNS-rebinding)
FOURA_MCP_ALLOWED_ORIGINS https://mcp.foura.ai,https://claude.ai,https://app.cursor.sh,https://app.cursor.com Списък с разрешени origins за браузърни клиенти
FOURA_MCP_RESOURCE_METADATA_URL https://foura.ai/docs/mcp/server#auth URL, върнат в WWW-Authenticate при 401

Работи като uid 1001 (non-root) в официалния контейнер. Споделената папка (host bind mount) /data/payloads трябва да бъде достъпна за запис от този uid.

Мащабирайте хоризонтално зад всеки load balancer. Клиентите предоставят своя ключ при всяка request, така че няма нужда от sticky session.

Обновено: 1 юли 2026 г.
Грешки на MCP Server →