文档 › MCP 参考 › MCP 服务器

MCP 服务器

MCP Server

可从任何 Model Context Protocol 客户端 (Claude Desktop, Claude Code, Cursor, Windsurf, VS Code) 将 FourA 作为四个原生工具和六个工作流提示词使用。无需集成代码，无需自定义 HTTP 客户端。

在 GitHub 上开源；在 npm 上的名称为 @fouradata/mcp。当前版本：0.5.0。

快速开始：本地 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 (在 macOS 上为 Cmd+Q)。如果应用仍在运行，它会在退出时用其内存中的配置覆盖您的修改。

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

重启客户端。这些工具 (foura_auto, foura_single, foura_proxy, foura_browser) 以及六个提示词将出现在您的工具列表中。

快速开始：托管模式 (Streamable HTTP)

对于支持 Streamable HTTP 传输的客户端 (Cursor, Windsurf, VS Code 以及带有 --transport http 的 Claude Code)，请将它们指向托管 endpoint，而不是运行本地子进程：

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

对于 Claude Desktop，请使用上方的 stdio 配置，或通过 mcp-remote 桥接托管 endpoint:

{
  "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
传输 流式 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 质询 WWW-Authenticate: Bearer realm="foura-mcp", resource_metadata="https://foura.ai/docs/mcp/server#auth"

托管服务器是无状态的。每个请求都自带密钥，服务器将其作为 X-API-Key 转发到 FourA API。一个密钥可打开所有四个工具。

为了防范 DNS 重绑定攻击 (CVE-2025-66414)，服务器会验证 Host header（必须是 mcp.foura.ai 或 localhost），并在存在时验证 Origin header（允许列表：mcp.foura.ai、claude.ai、app.cursor.sh、app.cursor.com）。服务器到服务器的调用方（curl、stdio 桥接模式下的 MCP 客户端）不发送 Origin 并直接通过。

工具

根据 MCP 2025-06-18 规范，所有四个工具均标注为 readOnlyHint: true 和 openWorldHint: true。自动批准受信任的只读工具的客户端可以无须每次请求确认弹窗即可调用它们。

foura_auto 是智能默认选项：给它一个 URL，它就会返回内容，并为你选择拉取方法。另外三个是它所编排的底层基元；当你需要精确控制时，可以使用它们。

foura_auto

当你希望 FourA 选择 request 方法时，给它一个 URL。它会在可用的 HTTP、proxy 和浏览器路径上进行有限次尝试。在受保护的目标上传递 validate，以便响应必须包含可识别真实页面的内容。如果没有一次尝试满足验证，该工具将返回错误，而不是将验证页面作为成功结果呈现。

响应在 meta 中包含完成详细信息，并且默认包含一个可重用的 session，其中带有 proxy、cookies 和 userAgent。对于简单的后续操作，请调用 foura_single，将 session.proxy 作为 proxy，将 cookie 序列化为 Cookie header，并将 session.userAgent 作为 User-Agent header 发送。对于 JavaScript 渲染，将会话值传递给匹配的 foura_browser 字段。

foura_single

发出一个 HTTP 请求，返回一个响应。与 POST /api/single/ 保持一一对应。

用于静态页面、JSON API、服务端渲染的 HTML。

选择要呈现的浏览器

请求默认呈现最新版的 Google Chrome。当目标接受某个浏览器而拒绝另一个浏览器时，请设置 browser（Chrome、Edge、Safari、Firefox 或 Tor）、os（Windows、macOS、Android 或 iOS）或 version，或传递确切的 profile id：

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

当多个配置文件匹配时，最新版本优先。如果组合不存在，则返回列出可用选项的错误，因此永远不会以您未选择的浏览器发送 request。选择需要 unblocker，该选项默认开启。目录发布在 GET /api/profiles，无需 API 密钥。

相同的四个字段位于 foura_proxy 的 request 对象内。

foura_proxy

通过带有自动重试的轮换 proxy 路由一个 HTTP request。当 foura_single 被阻止或目标需要特定出口国家时使用它。

将 exitCountries 设置为由用户或目标要求提供的双字母目标可见国家代码的严格许可名单：

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

值会被去除空格、转为大写并去重。不含未知出口的 proxy 会被排除，并且请求绝不会回退到未请求的国家/地区。选择过程使用最新可用的对目标可见的国家/地区元数据，通常会在十分钟内更新；这不是在请求期间进行的实时地理位置查找。请勿从 proxy 主机地址推断服务所在的国家/地区。

限定范围内的成功会返回 exitCountry 以及可复用的 proxy ID。检查 exitCountry 是否属于请求的允许列表。如果当前池没有匹配项，工具会在 details.exitCountries 中返回规范化范围的 code: "no_eligible_proxy"。保留该范围并在稍后重试。仅在用户明确更改要求时才更改或扩大该范围。

如果选定的页面后来需要 JavaScript，请将返回的 proxy ID 传递给 foura_browser.proxy，以便浏览器复用相同的出口。

foura_browser

完整浏览器会话。运行 JavaScript、渲染 DOM 且返回 cookie。对应 POST /api/browser/。

适用于单页应用、延迟加载的内容，或处于需要真实浏览器才能通过的防机器人质询之后的页面。

有关每个工具的输入格式、默认值和验证规则，请参阅 REST endpoint 参考。工具架构与 REST API 字段逐一对应，并添加了仅限 MCP 的 offload_large 选用项（见下文）。

当目标运行机器人检查时

如果目标在到达 body 之前运行了机器人检查，foura_single 和 foura_proxy 会返回 defense。defense.solved: true 表示通过了检查，并且 data 是实际页面；false 表示 body 可能是质询页面。使用不同的 browser、os 或 version 重试，或者升级到 foura_proxy 或 foura_browser，而不是将质询页面视为内容。

类型化响应

每个工具的响应都包含 content（人类可读的文本摘要）和 structuredContent（根据工具的 outputSchema 验证的类型化 JSON）。每个工具都有其独特的格式：

  • foura_auto：单一格式的 { status, headers, data } 加上 meta（{ rung, solved, attempts, credits }，始终存在，其中 rung 是 cache、probe、proxy、browser、fail 之一），默认情况下，还包括 session ({ proxy, cookies, userAgent }) 用于通过较低级别工具进行重放。没有 total_time。
  • foura_single：{ status, headers, data, total_time, ... }（headers 是一个数组，每个重定向跳转对应一个条目）
  • foura_proxy：与单一工具相同加上 { proxy, total }；限定范围内的成功还包括 exitCountry
  • foura_browser：独特的格式 { status, headers: object, body, cookies, userAgent }（注意：取决于 content-type，body 可以是字符串或对象）

支持 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=/"]
    }
  ]
}

这对于在一次 response 中设置 session + 追踪 + 同意 cookie 的网站（大多数电子商务网站）很重要。

大型 response：offload_large（默认：inline）

默认情况下（从 v0.2.0 开始），完整的 response body 会在 structuredContent 中以内联方式返回，无论大小。这在所有 MCP 客户端中都可以开箱即用。

如果您的客户端支持 MCP resources/read 并且您希望在大型页面上节省 token，请在每次工具调用时传递 offload_large: true。大于或等于 50 KB 的 response 将被写入磁盘，作为 resource_link 返回，您的客户端仅在实际需要时才获取 body。缓存的 payload 在 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 支持

租户隔离：每个 API 密钥拥有独立的命名空间 (sha256(apiKey)[:16])。只有存储 payload 的密钥才能将其读取。跨租户读取将返回 Payload not found 且不会泄漏是否存在。

内置 Prompts

六个工作流模板在任何 MCP 客户端的 /prompts 下显示。每个模板接受命名参数，并返回协调一个或多个工具的模板化用户消息。

Prompt 参数 功能
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 (逗号分隔) 并行单次抓取，每个 URL 自动降级至 proxy，仅返回元数据

闲置时 Prompts 消耗零个 token。仅调用的 Prompts 会进入 LLM 上下文。

全文加手动降级 prompts: MCP Recipes。

错误封装

每个错误 (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 n/a 目标 IP 在私有或保留范围内 (RFC 5735, 6598, IPv6保留) 否，更改 URL
upstream_non_json 变化 上游返回格式错误的 body 可能，需调查
output_validation_failed n/a MCP 服务器的 outputSchema 拒绝了上游 response (服务器错误或意外的上游形状) 可能，请报告
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 其他 防御性，在实践中不应出现 调查
no_eligible_proxy n/a 没有 proxy 与严格的 exitCountries 作用域匹配 稍后重试；仅显式更改作用域

LLM 代理可以直接读取 code 进行重试逻辑，而无需解析散文。Authentication 演练：Authentication。

Limits

  • 默认内联 body。带有 offload_large: true 时，>= 50 KB 的 responses 会存入磁盘 + resource_link (按租户，1小时 TTL)。
  • 在 MCP 层拒绝私有目标 (RFC 5735, RFC 6598, IPv6 保留块)。仅转发公共主机。
  • 传入的 /mcp requests 的 request body 上限为 256 KB (真实的 MCP payloads < 4 KB)。
  • Rate limits 由 FourA API 针对每个服务强制执行。参阅 Rate Limits。

Self-Hosting

完整的服务器源代码在 @fouradata/mcp 下的 GitHub 上公开。克隆仓库，npm install，npm run build，并运行 node dist/http.js 以建立您自己的实例。在任何负载均衡器后面的单个容器中无状态运行。

可配置环境：

变量 默认值 用途
PORT 3076 HTTP 监听端口
FOURA_API_BASE https://api.foura.ai/api 上游 FourA REST 基础 URL
FOURA_MCP_PAYLOADS_DIR /data/payloads 大于等于 50 KB 的响应在磁盘上的缓存位置 (使用 offload_large: true)
FOURA_MCP_ALLOWED_HOSTS mcp.foura.ai,localhost,127.0.0.1,[::1] 用于 Host header 的主机名白名单 (防御 DNS 重绑定)
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 401 时在 WWW-Authenticate 中返回的 URL

官方容器作为 uid 1001 (非 root) 运行。/data/payloads 主机绑定挂载必须可由该 uid 写入。

可在任何负载均衡器后方进行水平扩展。客户端在每次 request 中都会提供其密钥，因此没有会话保持。

更新于： 2026年8月6日
MCP Server Errors →