OpenCode + Scrapeless: 连接远程MCP服务器

TL;DR:

• OpenCode将Scrapeless作为一个 remote MCP服务器在 opencode.json。 入口需要一个 url、一个 x-api-token 头部和 "oauth": false。
• 将密钥写为 {env:SCRAPELESS_API_KEY}，而不是 ${SCRAPELESS_API_KEY}。 OpenCode替换第一种形式并将第二种形式作为文本发送，服务器仍然列为已连接，而每个工具调用都因401而失败。
• ✓ connected 仅证明头部存在。 Scrapeless握手接受任何 x-api-token 值，并仍然列出所有25个工具，因此在信任设置之前请先读取一个工具结果。
• oauth 设置决定了Bearer错误的样子。 默认情况下，Authorization: Bearer 头部显示 ⚠ needs authentication；使用 "oauth": false 时同一头部显示 ✗ failed 以及401。
• 工具以 <server>_<tool> 命名到达。 一个称为 scrapeless 的服务器条目提供模型 scrapeless_scrape_markdown，这25个定义以大约30KB的 tools/list 响应返回。
• 在 Scrapeless免费计划 上获取密钥，并在几分钟内连接OpenCode。

OpenCode在您的终端中针对您配置的任何模型提供者运行一个编码代理。它读取文件并运行命令，但关于实时网页的问题需要一个获取网页的工具，而MCP服务器是OpenCode获取它未附带的工具的方式。

Scrapeless MCP服务器是托管的，因此连接它属于配置而不是安装。本指南涵盖配置条目、静默中断的替换语法、每个 opencode mcp list 状态的含义，以及如何区分有效密钥与仅仅连接的服务器。

OpenCode 从 Scrapeless 获取的内容

服务器列出了25个工具。三个在一次调用中返回一个页面： scrape_markdown、 scrape_html 和 scrape_screenshot。十六个 browser_* 工具，例如 browser_create、 browser_goto、 browser_click 和 browser_type，逐步驱动云浏览器会话。 crawl_start、 crawl_result 和 crawl_cancel 管理抓取，而 google_search、 google_trends 和 ai_scraper 完成该集合。

对于大多数提示，有用的是 scrape_markdown。它以Markdown格式返回渲染页面，这是模型最便宜读取的形状，它只需要一个URL。

先决条件

• OpenCode，已经配置了模型提供者。本指南使用OpenCode 1.17.19。
• 来自Scrapeless仪表板的Scrapeless API密钥。
• 服务器无需安装。它在 https://api.scrapeless.com/mcp 执行，OpenCode通过HTTP访问它。

第一步：将服务器添加到 opencode.json

OpenCode 从其配置的 mcp 块中读取MCP服务器。全局文件是 ~/.config/opencode/opencode.json，项目根中的 opencode.json 适用于该项目：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "scrapeless": {
      "type": "remote",
      "url": "https://api.scrapeless.com/mcp",
      "oauth": false,
      "headers": {
        "x-api-token": "{env:SCRAPELESS_API_KEY}"
      }
    }
  }
}

"type": "remote" 使OpenCode通过HTTP连接，而不是启动本地命令。 "oauth": false 阻止它启动OAuth流程，因为Scrapeless端点不提供此功能；它的OAuth发现路径返回404，并且仅在头部上进行身份验证。 opencode mcp add 还可以写入条目并接受 --url 和 --header 标志，但直接编辑文件是将 {env:} 引用准确设定的可靠方法。

第二步：使用 {env:} 替代，而不是 ${}

OpenCode 在加载配置时用该环境变量的值替换 {env:VARIABLE_NAME}。环境变量通常是不同机器之间更改的凭证的常规存放地，正如 十二因素应用的配置指南 所推荐的那样，而 {env:} 是OpenCode读取它们的方式。在启动OpenCode的终端中导出密钥：

export SCRAPELESS_API_KEY="your-scrapeless-api-key"
opencode mcp list

●  ✓ scrapeless connected
│      https://api.scrapeless.com/mcp

Shell风格的 ${SCRAPELESS_API_KEY} 看起来等效，但并非如此。OpenCode将其作为文本传递，因为Scrapeless握手接受任何非空令牌，服务器仍然列出 ✓ connected。问题仅在模型调用工具时出现：

Failed to fetch data. Error: [Scrapeless]: Request POST /api/v1/unlocker/request failed with status 401

未导出变量更早且更明显地失败。{env:SCRAPELESS_API_KEY} 指向无效时，握手本身被拒绝：

●  ✗ scrapeless failed
│      SSE error: Non-200 status code (401)
│      https://api.scrapeless.com/mcp

现在设置这个？ Scrapeless免费计划 涵盖连接和您的第一个工具调用。

第三步：阅读每个 opencode mcp 列状态

状态行说明OpenCode是否能够打开连接。它并没有说明密钥是否有效。

一种失败模式看起来像是一个坏密钥，但实际上并非如此。如果状态行显示已连接，并且工具调用返回 Failed to fetch data，请检查机器上是否还有其他 MCP 服务器暴露相同的 Scrapeless 工具，例如路由多个提供商的网关，这些提供商在单一凭证后面。代理可能已调用了那个。OpenCode 在每个工具前面加上它的服务器名称，因此抄本行命名了响应的服务器。

大多数 MCP 示例使用 Authorization: Bearer 进行身份验证，该方案由 OAuth 2.0 Bearer Token 规范 定义。Scrapeless 则读取 x-api-token，因此 Bearer 头获得 401 未授权响应。在 oauth 默认为其默认值时，OpenCode 将该 401 视为登录提示：

●  ⚠ scrapeless needs authentication
│      https://api.scrapeless.com/mcp

使用 "oauth": false，相同的头部在 401 时读取 ✗ failed，这比邀请进行身份验证更准确地描述了错误的头部。

第 4 步：从提示调用工具

第一次命名服务器和工具，这样结果只有一个可能的来源：

Use the scrapeless MCP server's scrape_markdown tool on https://example.com
and reply with the first markdown heading line.

opencode run --format json 打印每一步作为 JSON 事件。该提示的工具事件：

type: tool_use
tool: scrapeless_scrape_markdown
status: completed
output: Response: "# Example Domain\n\nThis domain is for use in documentation ...

模型的回复为 # Example Domain。工具名称遵循 OpenCode 的 <server>_<tool> 模式，因此名为 scrapeless 的输入为所有 25 个工具添加了相同的前缀。

该输出是 opencode mcp list 无法给出的检查。以页面内容开头的结果意味着密钥有效。以 Failed to fetch data 开头的结果意味着连接正常，但密钥无效。MCP 工具规范 为失败调用提供一个 isError 标志，但 Scrapeless 将两个结果作为普通工具文本返回，而没有它，因此文本就是需要读取的内容。

每个连接的服务器还将其工具定义添加到模型的上下文中，Scrapeless tools/list 对所有 25 个工具的响应大约为 30 KB。在条目上设置 "enabled": false 可保持其配置，但在不需要 Web 的会话中不使用它。

关于服务器暴露的内容， Scrapeless MCP 服务器公告 涉及启动情况，而我们的 MCP 集成指南 比较了代理到达浏览器的方式。浏览器 MCP 文档 提供配置参考，抓取 API 页面描述了工具背后的参与者，而 定价 列出了调用的费用。

结论

OpenCode 需要来自条目的四个事项： "type": "remote"，Scrapeless URL，一个作为 {env:SCRAPELESS_API_KEY} 编写的 x-api-token 头，以及 "oauth": false。替换语法是最有可能出错的细节，因为断开的形式仍然可以连接。

opencode mcp list 捕获缺失的头部、未导出的变量和 Bearer 混淆。只有工具结果可以捕获坏密钥，因此请进行一次调用并阅读返回的内容，然后再在连接上构建任何内容。

准备好让 OpenCode 直播网络视图了吗？ 从 Scrapeless 免费计划开始 并添加服务器。

常见问题解答

问：我如何将带有 API 密钥头的远程 MCP 服务器添加到 OpenCode？

在 mcp 下的 opencode.json 中添加一个条目，包含 "type": "remote"、服务器 url、"oauth": false 和一个 headers 对象。对于 Scrapeless，头部为 x-api-token，以 {env:SCRAPELESS_API_KEY} 的形式书写，因此密钥不会出现在文件中。

问：为什么 ${SCRAPELESS_API_KEY} 在 opencode.json 中不起作用？
OpenCode的替代语法是{env:SCRAPELESS_API_KEY}。shell风格的形式作为文字文本发送，因此服务器仍然显示为已连接，并且工具调用返回failed with status 401。

问：为什么opencode mcp列表显示需要认证？

服务器在oauth启用时返回了401，因此OpenCode提供了登录选项。对于Scrapeless，这几乎总是意味着Authorization: Bearer头部；切换到x-api-token并设置"oauth": false。

问：“连接”是否意味着我的Scrapeless密钥有效？

不是。Scrapeless握手和工具列出在任何非空的x-api-token值下成功。只有工具调用会暴露一个错误的密钥，结果是以Failed to fetch data开头。

问：OpenCode内部的Scrapeless工具名称是什么？

OpenCode将MCP工具命名为<server>_<tool>。条目称为scrapeless，模型看到scrapeless_scrape_markdown，并且其他24个工具都有相同的前缀。

问：OpenCode从哪里读取opencode.json？

全局配置是~/.config/opencode/opencode.json，项目可以在其根目录中添加自己的opencode.json。OPENCODE_CONFIG环境变量将OpenCode指向特定的配置文件。

问：我需要为Scrapeless MCP服务器安装包吗？

不需要。服务器托管在https://api.scrapeless.com/mcp，OpenCode通过HTTP连接到它，因此没有包，没有本地进程，也没有版本需要更新。