MCP Server
MCP Server
在任何 Model Context Protocol 客户端（Claude Desktop、Claude Code、Cursor、Windsurf、VS Code）中将 FourA 作为三个原生工具和五个工作流提示词使用。无需集成代码，无需自定义 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（macOS 上为
Cmd+Q）。如果应用程序仍在运行，它将在退出时用其内存中的配置覆盖您的修改。
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）和五个提示词将显示在您的工具列表中。
快速开始：托管（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 版本不支持直接使用 url 形式。请对 Claude Desktop 使用上述 stdio 配置，或者通过 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) |
| 认证 | 每次 request 携带 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" |
托管服务端是无状态的。每个 request 都会携带自己的密钥，服务端会将其作为 X-API-Key 转发给 FourA API。一个密钥即可启用所有三个工具。
为了防御 DNS 重新绑定（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、stdio 桥接模式下的 MCP 客户端）不发送 Origin，可直接通过。
工具
根据 MCP 2025-06-18 规范，所有三个工具都标注了 readOnlyHint: true 和 openWorldHint: true。自动批准受信任只读工具的客户端在调用它们时无需每次 request 都弹出确认弹窗。
foura_single
单次 HTTP request，返回 response。耗时 200ms 到 2s。一对一映射 POST /api/single/。
适用于静态页面、JSON API、服务端渲染的 HTML。
foura_proxy
通过动态轮换 proxy 池路由并支持自动重试的 HTTP request。耗时 1 到 5s。映射 POST /api/proxy/。
当 foura_single 返回 403、CAPTCHA 或地理限制内容时使用。response 中包含成功的 proxy ID（proxy）和以秒为单位的外部实际耗时（total，浮点数）。
foura_browser
完整的浏览器会话。运行 JavaScript、渲染 DOM、返回 cookie。耗时 2 到 10s。映射 POST /api/browser/。
适用于单页面应用（SPA）、延迟加载的内容，或需要真实浏览器才能通过的防爬虫挑战页面。
有关每个工具的输入结构、默认值和验证规则，请参阅 REST endpoint 参考。工具的 schema 与 REST API 逐字段对应，并额外支持仅限 MCP 的 offload_large 选项（见下文）。
类型化 response
每个工具 response 都包含 content（人类可读的文本摘要）和 structuredContent（根据工具的 outputSchema 验证过的类型化 JSON）。每个工具都有其独特的结构：
foura_single：{ status, headers, data, total_time, ... }（headers 是一个数组，每次重定向跳转对应一个条目）foura_proxy：与 single 相同，外加{ proxy, total }（其中total是浮点数秒，包含重试在内的外部总耗时）foura_browser：独特的结构{ status, headers: object, body, cookies, userAgent }（注意：根据 content-type 的不同，body可能是字符串或对象）
支持 structuredContent 的客户端（截至 2026 年的 Claude Desktop、Cursor、Windsurf）会将类型化对象直接传递给 LLM，从而跳过 JSON 转字符串的重新分词（re-tokenization）过程。预计在典型 response 中可节省 30% 到 40% 的 token。
多值 response header
多次出现的 header（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 中设置会话、追踪和同意 cookie 的网站（大多数电商网站）至关重要。
大体积 response：offload_large（默认：内联）
默认情况下（自 v0.2.0 起），无论大小如何，完整的 response body 都会内联返回在 structuredContent 中。这在所有 MCP 客户端中都是开箱即用的。
如果您的客户端支持 MCP resources/read 并且您希望在处理大页面时节省 token，请在每次工具调用时传递 offload_large: true。大于等于 50 KB 的 response 将被写入磁盘，并作为 resource_link 返回，您的客户端仅在实际需要时才获取 body。缓存的数据将在 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 插件 | 已支持 |
租户隔离：每个 API key 都有自己的命名空间（sha256(apiKey)[:16]）。只有存储了该数据的密钥才能将其读取。跨租户读取将返回 Payload not found，且不会泄露数据是否存在的信息。
内置提示词（Prompts）
在任何 MCP 客户端中，/prompts 下都会显示五个工作流模板。每个模板都接受命名参数，并返回一个模板化的用户消息，用于编排一个或多个工具。
| 提示词 | 参数 | 功能 |
|---|---|---|
scrape_product_page |
url |
浏览器获取，然后以 JSON 格式提取商品标题、价格、图片、库存和 SKU |
extract_article |
url |
使用 single 获取并支持 proxy 回退，然后去除导航/广告并返回干净的文章 JSON |
monitor_pricing |
url，可选 target_price |
使用 proxy 获取，提取当前价格，并与目标价格进行对比 |
check_endpoint_health |
url，可选 expected_text |
使用 single 进行严格验证，返回可达性和耗时 |
bulk_fetch_urls |
urls（逗号分隔） |
并行 single 获取，每个 URL 自动回退到 proxy，仅返回元数据 |
闲置时提示词不消耗任何 token。只有被调用的提示词才会进入 LLM 上下文。
完整文本及手动回退提示词：MCP 秘籍。
错误包装（Error envelope）
每个错误（isError: true）都携带一个 structuredContent 包装。每个错误包含的最少字段：
{
"service": "single | proxy | browser",
"code": "rate_limited",
"error": "Rate limit exceeded"
}
对于带有 HTTP 状态码的上游错误，还会存在 status 字段。对于 rate limit 和容量错误，上游包装会增加 retryAfter、current.{concurrency, rpm} 以及 limits.{maxConcurrency, maxRpm}。有关底层的 REST 结构，请参阅 API 错误。
固定的 code 值：
| Code | HTTP | 含义 | 重试安全？ |
|---|---|---|---|
ssrf_blocked |
n/a | 目标 IP 处于私有或保留网段（RFC 5735, 6598, IPv6 保留网段） | 否，请更改 URL |
upstream_non_json |
变化 | 上游返回了格式错误的 body | 可能，请排查 |
output_validation_failed |
n/a | MCP 服务端的 outputSchema 拒绝了上游 response（服务端 bug 或非预期的上游结构） |
可能，请报告 |
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 进行重试逻辑，而无需解析文本。认证指南：认证。
限制
- 默认内联 body。使用
offload_large: true时，大于等于 50 KB 的 response 将写入磁盘并返回resource_link（按租户隔离，1 小时 TTL）。 - 在 MCP 层拒绝私有目标（RFC 5735、RFC 6598、IPv6 保留网段）。仅转发公共主机。
- 传入的
/mcprequest 的 body 大小限制为 256 KB（实际的 MCP payload 小于 4 KB）。 - Rate limit 由 FourA API 按服务强制执行。请参阅 Rate Limits。
自托管
每个实例都在一个容器中无状态运行。公共 GitHub 镜像将在 v1.0 版本推出。在此之前，源码保存在私有仓库中，容器镜像可根据要求提供。请联系 support@foura.ai 获取早期访问权限。
可配置的环境变量：
| 变量 | 默认值 | 用途 |
|---|---|---|
PORT |
3076 |
HTTP 监听端口 |
FOURA_API_BASE |
https://api.foura.ai/api |
上游 FourA REST 基础 URL |
FOURA_MCP_PAYLOADS_DIR |
/data/payloads |
大于等于 50 KB 的 response 在磁盘上的缓存路径（启用 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 中提供其密钥，因此无需粘性会话（sticky session）。