# MCP 服务器

> URL: https://foura.ai/zh/docs/mcp/server
> Updated: 2026-11-13
> Index: https://foura.ai/llms.txt

# MCP 服务端

通过任何 [Model Context Protocol](https://modelcontextprotocol.io) 客户端（Claude Desktop、Claude Code、Cursor、Windsurf、VS Code），将 FourA 作为 4 个原生工具和 6 个工作流提示词使用。无需编写集成代码，无需自定义 HTTP 客户端。

在 [GitHub](https://github.com/fouradata/mcp) 上开源；在 [npm](https://www.npmjs.com/package/@fouradata/mcp) 上的包名为 `@fouradata/mcp`。当前版本：`0.8.3`。

## 快速入门：本地 stdio（推荐用于 Claude Desktop）

在 [foura.ai/dashboard#api-keys](https://foura.ai/dashboard#api-keys) 获取密钥（一键生成，格式为 `pk_live_...`，后续可通过 **Reveal** 再次查看密钥）。将以下内容添加到你的 MCP 客户端配置中：

```json
{
  "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 extension) | `.vscode/mcp.json`，位于顶级 `servers` 键下，而非 `mcpServers` |

重启客户端。这些工具（`foura_auto`、`foura_single`、`foura_proxy`、`foura_browser`）以及 6 个 prompt 将显示在工具列表中。

## 快速开始：托管版 (Streamable HTTP)

对于支持 Streamable HTTP 传输的客户端（Cursor、Windsurf、VS Code、带有 `--transport http` 的 Claude Code），请直接指向托管 endpoint，而不是运行本地子进程：

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

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

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

## 托管端点参考

| 属性 | 值 |
|---|---|
| URL | `https://mcp.foura.ai/mcp` |
| 传输协议 | 可流式传输 HTTP (POST `/mcp`，SSE 响应) |
| 认证方式 | 每个请求携带 `Authorization: Bearer pk_live_...`。直接在 `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 质询 | `WWW-Authenticate: Bearer realm="foura-mcp"` |

401 质询特意不包含 RFC 9728 `resource_metadata` 参数。声明该参数会导致支持 OAuth 的客户端启动本服务器未实现的流程。将你的 `pk_live_` 密钥作为 Bearer 令牌发送，即可消除 401。

托管服务器是无状态的。每个请求均携带独立的密钥，服务器会将其作为 `X-API-Key` 转发至 FourA API。单个密钥即可解锁全部四个工具。

为防御 DNS 重新绑定 (CVE-2025-66414)，服务器会验证 `Host` 请求头 (必须为 `mcp.foura.ai` 或 localhost) 以及 `Origin` 请求头 (存在时，白名单为：`mcp.foura.ai`、`claude.ai`、`app.cursor.sh`、`app.cursor.com`)。服务端到服务端的调用方 (`curl`、处于 stdio 桥接模式的 MCP 客户端) 不发送 `Origin`，可直接通过。

## 工具

根据 [MCP 2025-06-18 规范](https://modelcontextprotocol.io/specification/2025-06-18/server/tools)，所有四个工具均已添加 `readOnlyHint: true` 和 `openWorldHint: true` 注解。自动批准受信任只读工具的客户端无需针对每次请求弹出确认窗口即可直接调用。

`foura_auto` 是智能默认项：提供一个 URL，它会为你选择抓取方式并返回内容。另外三个工具是它所编排的底层原语；当需要显式控制时可以使用它们。

### foura_auto

在需要 FourA 自主选择请求方式时提供一个 URL。它会在可用的 HTTP、proxy 和浏览器路径中进行有限次数的尝试。针对受保护的目标传入 `validate`，以确保响应必须包含能够识别真实页面的内容。若所有尝试均未满足验证条件，该工具将返回错误，而不会将质询页面视为成功返回。

响应在 `meta` 中包含完成详情，并且默认提供包含 `proxy`、`cookies` 和 `userAgent` 的可重用 `session`。进行后续普通请求时，请调用 `foura_single` 并将 `session.proxy` 设为 `proxy`，将 cookie 序列化为 `Cookie` 请求头，并将 `session.userAgent` 作为 `User-Agent` 请求头发送。对于 JavaScript 渲染，请将会话值传入对应的 `foura_browser` 字段。

设置 `exitClass: "premium"`，允许 Auto 在标准池无法访问页面时升级到高级出口节点。`exitClass: "standard"` 与省略该字段都会使 Auto 保持在标准池中，并且只有指定了类别的请求才会返回 `exitClass`。它的工作机制与 `foura_proxy` 相同：是一种额度配额，而非强制指令，计入您计划中的高级流量配额，若计划不含高级出口节点则会以 `code: "plan_limit_premium"` 拒绝。结果中的 `exitClass` 会标明实际交付的类别。请参阅 [Smart Fetch 中的 exitClass](https://foura.ai/docs/api/endpoints#exitclass-on-smart-fetch)。

### foura_single

单次 HTTP 请求并返回响应。与 [`POST /api/single/`](https://foura.ai/docs/api/endpoints) 一一对应。

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

#### 选择呈现的浏览器

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

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

当多个 profile 匹配时，以最新版本为准。如果请求的组合不存在，系统将返回错误并列出可用配置，确保绝不会以未指定的浏览器发送 request。匹配选择需要启用 `unblocker`（默认开启）。目录发布在 [`GET /api/profiles`](https://foura.ai/docs/api/endpoints)，无需 API key。

`foura_proxy` 的 `request` 对象中包含相同的四个字段。

### foura_proxy

通过轮换 proxy 路由单个 HTTP request，并支持自动重试。当 `foura_single` 被封禁或目标站点需要特定出口国家/地区时使用。

将 `exitCountries` 设置为由用户或目标需求指定的两位字母国家/地区代码严格白名单：

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

值会被去除首尾空格、转为大写并去重。国家未知的标准池出口会被排除，且标准池绝不会回退到未请求的国家。高级出口也会保持在列表中：使用 `exitClass: "premium"` 时，标准池仍会优先尝试，高级出口会从您指定的某个国家发出，并在 `exitCountry` 中标明。选择依据是最新的目标可见国家元数据，通常在十分钟内更新；这不是请求期间的实时地理位置查询。请勿根据代理主机地址推断提供服务的国家。

限制范围成功的请求会返回 `exitCountry` 以及可复用的 `proxy` ID。请检查 `exitCountry` 是否属于请求的白名单。如果当前池中没有匹配项，该工具会返回 `code: "no_eligible_proxy"`，并在 `details.exitCountries` 中附带规范化后的范围。请保留该范围并在稍后重试。仅当用户明确更改要求时才更改或放宽该范围。从 Startup 方案开始包含国家范围限定。在不包含该功能的方案中，发送 `exitCountries` 的调用会被拒绝，并返回 `403` 和 `X-FourA-Limit: plan_limit_feature`。

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

为无论尝试多少次出口标准池都无法访问的目标设置 `exitClass: "premium"`。这是一个许可，而非强制指令：标准池仍会优先竞争响应并通常胜出，在尝试任何高级出口前由标准池响应的请求不消耗高级流量。高级尝试即使失败也会计入所产生的流量。响应会返回 `exitClass`（`premium` 或 `standard`），以便您查看每个请求由哪各类别的出口提供服务。方案中包含的高级流量耗尽后，返回 `standard` 也是正常结果而非错误。`exitClass: "standard"` 会完全禁止升级。在没有高级出口的方案中使用 `exitClass: "premium"` 会被拒绝并返回 `code: "plan_limit_premium"`。参见 [exitClass](https://foura.ai/docs/api/endpoints#exitclass)。

当轮换必须切换到另一个浏览器才能获取响应时，成功的响应会携带 `profile`：即最终选定的目录配置文件 ID。在下一次调用中将其作为 `profile` 传入，以呈现相同的浏览器。

轮换失败时，错误旁边会携带 `attemptReport`：包含一句 `summary`，以及分别统计从未响应的出口（`noResponse`）、被机器人检查拒绝的出口（`defense`，厂商见 `vendors`）、已送达但仅被您自己的 `validate.data` 拒绝的页面（`contentRejected`）、`statusRejected` 和 `other`。`profilesTried` 按首次使用顺序顺序列出任务发送的浏览器，其中 `default` 表示请求完全按原样发出。较高的 `contentRejected` 意味着 FourA 交付了真实页面，但您自己的规则将其丢弃。参见 [为什么代理请求用尽了重试次数](https://foura.ai/docs/troubleshooting/proxy-attempt-report)。

### foura_browser

完整浏览器会话。执行 JavaScript，渲染 DOM，返回 cookie。对应 [`POST /api/browser/`](https://foura.ai/docs/api/endpoints)。

适用于单页应用（SPA）、懒加载内容或包含需要真实浏览器才能完成的人机验证的页面。

有关各工具的输入结构、默认值和验证规则，请参阅 [REST endpoint 参考](https://foura.ai/docs/api/endpoints)。工具 schema 与 REST API 一致，外加仅限 MCP 的 `offload_large` 选项（见下文），但有两个例外：`foura_browser` 没有 `lean` 字段，`foura_proxy` 暂无 [出口位置](https://foura.ai/docs/api/endpoints#exit-location)字段。在这些名称下传递的值永远不会到达 API。如需配置，请直接调用 [`POST /api/browser/`](https://foura.ai/docs/api/endpoints) 或 [`POST /api/proxy/`](https://foura.ai/docs/api/endpoints)。

### 当目标执行 Bot 检查时

当目标在返回正文前执行了 Bot 检查时，`foura_single` 和 `foura_proxy` 会返回 `defense`。`defense.solved: true` 表示已通过检查且 `data` 为真实页面；`false` 则表示正文可能是验证页面。此时请使用不同的 browser、os 或 version 重试，或者升级到 `foura_proxy` 或 `foura_browser`，而不是将验证页面视为实际内容。

## 类型化响应

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

- `foura_auto`：单一结构的 `{ status, headers, data }` 加上 `meta`（`{ rung, solved, attempts, credits, attemptsByEngine, browserRequests }`，始终存在，其中 `rung` 是 `cache`、`probe`、`proxy`、`browser`、`warmup`、`fail` 之一），以及默认包含的 `session`（`{ proxy, cookies, userAgent }`），以便通过底层工具重放；指定了 class 的 request 还包含 `exitClass`。`meta.attemptsByEngine` 统计调用发送到 Single、Proxy 和 Browser 的 request 数量，`meta.browserRequests` 统计使用每日 Browser 配额的数量。调用失败时还包含 `attemptReport`。无 `total_time`。
- `foura_single`：`{ status, headers, data, total_time, ... }`（headers 为数组，每次重定向跳转对应一项）
- `foura_proxy`：与 single 相同，另加 `{ proxy, total }`；限定作用域成功时还包含 `exitCountry`，指定了 class 的 request 包含 `exitClass`，更改了浏览器系列的轮换包含 `profile`，失败时包含 `attemptReport`
- `foura_browser`：独立结构 `{ status, headers: object, body, cookies, userAgent }`（注意：`body` 可能为字符串或对象，取决于 content-type）

每个工具还会从 API 响应头中读取并报告调用消耗及追踪方式：

- `credits` - 本次调用消耗的 credits。请求失败时也会显示，因为相关工作已执行。系统仅对成功的调用计费，因此失败的请求虽然在此处显示 credits，但不会向您收费。
- `request_id` - FourA 对该调用的 id。提交支持请求时请附带此 id。
- `exitClass` - 当高级出口节点提供该调用服务时为 `premium`。在 `foura_single` 和 `foura_browser` 上，这会在 `proxy` 重放 `foura_proxy` 或 `foura_auto` 发现的高级出口时发生。

当 API 未报告任何内容时，这些字段均不存在，因此基于早期版本编写的客户端仍可正常运行。相同的值已记录在 [Response Headers](https://foura.ai/docs/api/response-headers) 中。

支持 `structuredContent` 的客户端可以直接将类型化对象传递给 LLM，而无需让其从正文中解析 JSON。

### 多值 response header

多次出现的 header（`Set-Cookie`、`Link`、`WWW-Authenticate`）以数组形式返回：

```json
{
  "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`（默认：inline）

默认情况下（自 v0.2.0 起），无论大小如何，完整 response body 都会以 inline 方式在 `structuredContent` 中返回。这在所有 MCP 客户端中均可开箱即用。

如果你的客户端支持 MCP `resources/read` 并且希望在大页面上节省 token，请在每次 tool 调用时传入 `offload_large: true`。大于等于 50 KB 的 response 将被写入磁盘，作为 `resource_link` 返回，客户端仅在实际需要时才获取该 body。在托管服务器上，缓存的 payload 会在 1 小时后过期。在自建实例上，系统不会自动删除存储的 payload：请自行清理 payload 目录中超过一小时的文件。

卸载的结果包含 `offloaded_resource_uri` 和 `size_bytes` 以代替 body。卸载的结果还会省略 `defense` 以及 `foura_proxy` 上的 `profile`，因此在需要读取这些字段的调用中请不要使用 `offload_large`。

```json
{
  "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 的 key 可以读取它。跨租户读取返回 `Payload not found`，不会泄露资源是否存在。

## 内置 Prompt

六个工作流模板在任何 MCP 客户端的 `/prompts` 下提供。每个模板接收命名参数，并返回编排一个或多个工具的模板化用户消息。

| Prompt | 参数 | 功能说明 |
|---|---|---|
| `smart_fetch` | `url`, 可选 `must_contain`, `extract` | 自动抓取 (选择方法并处理 Bot 防护)，然后返回或提取内容 |
| `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，仅返回元数据 |

Prompt 在空闲时不消耗 token。只有被调用的 prompt 才会进入 LLM 上下文。

完整文本及手动回退 prompt: [MCP Recipes](https://foura.ai/docs/mcp/recipes)。

## 错误响应结构

每个错误 (`isError: true`) 都包含一个 `structuredContent` 外层结构。所有错误包含的最少字段如下:

```json
{
  "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 错误](https://foura.ai/docs/api/errors)。

稳定的 `code` 值：

| 代码 | HTTP | 含义 | 是否可安全重试？ |
|---|---|---|---|
| `ssrf_blocked` | 不适用 | 目标为私有或保留地址（RFC 5735、6598、IPv6 保留），URL 不是 http(s)，或其主机名无法解析 | 否，检查 URL。短暂解析失败的情况可以重试 |
| `upstream_non_json` | 不定 | 上游返回格式错误的 body | 视情况而定，需要排查 |
| `output_validation_failed` | 不适用 | MCP 服务器的 `outputSchema` 拒绝了上游响应，或者工具完全无法完成调用（未配置 API key，API 无法访问） | 视情况而定：检查配置，然后上报 |
| `bad_request` | 400 | 输入结构被拒绝，目标 URL 指向了 FourA 自身的 API 而不是页面（该处仅能获取 `/inspect`），或者 URL 包含未编码的空格（应编码为 `%20`） | 否，修复参数 |
| `auth_failed` | 401 | Key 缺失、无效或已停用 | 否，修复 key |
| `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` | 其他 | request 已执行但未产生被接受的应答：在 `foura_single` 上目标从未响应（超时、连接被拒绝），以及在任何工具上你的 `validate` 拒绝了 2xx 或 3xx 响应。请阅读 `status` 和 `error` | 排查原因 |
| `no_eligible_proxy` | 不适用 | 没有 proxy 匹配严格的 `exitCountries` 范围 | 稍后重试；仅在明确需要时更改范围 |
| `plan_limit_*` | 403 或 429 | 你的套餐限制之一拒绝了本次调用：`plan_limit_` 后跟 `feature`、`premium`、`concurrency`、`rate`、`browser_daily`、`credits` 或 `bandwidth`。参见 [MCP 服务器错误](https://foura.ai/docs/mcp/errors) | 存在时等待 `retryAfter`；否则直到限制重置或套餐变更前不要重试 |

LLM agent 可以直接读取 `code` 用于重试逻辑，无需解析文本。认证指南：[Authentication](https://foura.ai/docs/getting-started/authentication)。

## 限制

- 默认内联 body。启用 `offload_large: true` 时，>= 50 KB 的响应会写入磁盘并返回 `resource_link`（按租户隔离，1 小时 TTL）。
- MCP 层会拒绝私有目标（RFC 5735、RFC 6598、IPv6 保留网段）。仅转发公共主机。
- 传入 `/mcp` 请求的 request body 上限为 256 KB（实际 MCP 有效载荷 < 4 KB）。
- Rate limit 由 FourA API 按服务分别强制执行。请参阅 [Rate Limits](https://foura.ai/docs/api/rate-limits)。

## 自托管

完整的服务器源码已在 [GitHub](https://github.com/fouradata/mcp) 上基于 `@fouradata/mcp` 开源。克隆该仓库，执行 `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` | 系统临时目录中的 `foura-mcp-payloads` 文件夹（配套的 Docker Compose 文件设置为 `/data/payloads`） | 缓存 >= 50 KB 响应的磁盘位置（启用 `offload_large: true` 时） |
| `FOURA_MCP_ALLOWED_HOSTS` | `mcp.foura.ai,localhost,127.0.0.1,[::1]` | `Host` 请求头的主机名白名单（防御 DNS 重绑定） |
| `FOURA_MCP_ALLOWED_ORIGINS` | `https://mcp.foura.ai,https://claude.ai,https://app.cursor.sh,https://app.cursor.com` | 浏览器调用方的 Origin 白名单 |

官方容器以 `uid 1001`（非 root）运行。配套的 Docker Compose 文件将 `/data/payloads` 保留在命名卷上；该路径下的主机绑定挂载必须对该 uid 可写。

可在任何负载均衡器后横向扩展。客户端在每次请求中提供其密钥，因此无需粘性会话。使用 `offload_large` 时，请将 `FOURA_MCP_PAYLOADS_DIR` 指向所有实例共享的存储，因为存储的有效载荷保存在写入它的实例磁盘上。`GET /healthz` 会返回 `ok`、`name` 和 `version`，便于负载均衡器探测实例状态。
