Warp + Scrapeless：连接远程 MCP 服务器

TL;DR:

• Warp 通过可流式传输的 HTTP 连接到 Scrapeless 作为远程 MCP 服务器。 在项目根目录下的一个 .warp/.mcp.json 文件中，包含 url 和 x-api-token 头部，即是完整的配置。
• 编写 ${SCRAPELESS_API_KEY}，包括大括号。 Warp 在读取文件时会扩展该表单。 $SCRAPELESS_API_KEY 和 {{SCRAPELESS_API_KEY}} 作为原文到达 Scrapeless，并且在 /mcp 中服务器仍然看起来健康。
• 未设置的变量会使整个文件失效。 其中的每个服务器都被 Warp config error … Missing or empty environment variable: SCRAPELESS_API_KEY 替换。
• 项目服务器手动启动。 打开 /mcp，选择 scrapeless 并按 Enter；行会从 offline 移动到 running · 25 tools。
• running · 25 tools 并不证明密钥。 一个虚构的密钥会达到相同的状态。一次工具调用，或步骤 5 中的简单检查，可以区分有效密钥和无效密钥。
• 头部名称是 x-api-token。 一个 Authorization: Bearer 条目会因“拒绝配置的凭证 (HTTP 401)”而失败，即使令牌本身是有效的。
• 在 Scrapeless 免费计划 上获取密钥，并在几分钟内添加服务器。

Warp 代理在真实终端中运行命令并读取您的代码，但它无法实时查看网页的渲染。MCP 服务器消除了这一差距：代理在任务中调用的工具，由一个获取并渲染页面的服务回答。

本指南将托管的 Scrapeless MCP 服务器添加到 Warp 代理 CLI，即 warp 二进制文件。配置是几行 JSON。它是否有效取决于三个细节：Warp 读取了哪个文件，密钥在其中是如何引用的，以及 /mcp 状态行告诉你什么和不告诉你什么。

Scrapeless 对 Warp Agent 会话的增强

服务器提供 25 种工具，按工作分组：

• scrape_markdown、scrape_html 和 scrape_screenshot 返回一个渲染页面，格式为 Markdown、原始 HTML 或图片，一次调用完成。
• 十六个 browser_* 工具，从 browser_create 和 browser_goto 到 browser_click、browser_type 和 browser_snapshot，逐步驱动云浏览器会话。
• crawl_start、crawl_result 和 crawl_cancel 在后台运行爬虫，稍后收集结果。
• google_search 和 google_trends 返回搜索结果和趋势数据，而 ai_scraper 从 AI 助手（如 ChatGPT、Gemini 和 Perplexity）捕获答案。

所有这些都不在您的机器上运行。MCP 可流式传输的 HTTP 传输 是一个接受 JSON-RPC 的单一 HTTPS 端点，Warp 原生支持。其 MCP 日志记录了 MCP: Using Streaming HTTP transport，无需在文件中设置任何传输。

Warp 查找 MCP 服务器定义的位置

Warp 从配置文件以及其设置页面读取服务器定义。Warp 的 MCP 文档 列出了这些位置：

来自任何提供者的项目范围服务器始终不会自行启动。Warp 会检测到它们并等待您启动每一个，并且该选择只持续到会话结束，因此在重启后必须重新启动它们。

CLI 还将配置与 Warp 应用程序分开。Warp Agent CLI 配置页面 将 ~/.warp_cli/.mcp.json 作为在 macOS 上的该文件。在 Linux 上，Warp Agent CLI v0.2026.09.09.08.26.stable_02 从 ~/.warp_cli/.mcp.json 或 ~/.warp/.mcp.json 中未能识别服务器，而是发现了所有三个项目范围文件，并将其标记为 Warp (.warp/.mcp.json)、Claude (.mcp.json) 和 Other Agents (.agents/.mcp.json)。本指南使用 .warp/.mcp.json，这是 Warp 将其命名为自己的文件。

如果您在 Warp 桌面应用中工作，相同的 mcpServers JSON 会通过 设置 > 代理 > MCP 服务器 通过 + 添加 按钮添加。

先决条件

• Warp Agent CLI，使用 Warp 账户登录。本指南使用的版本为 v0.2026.09.09.08.26.stable_02，warp --version 打印。
• 在该 Warp 账户上的 AI 积分，用于代理调用工具的步骤。
• 从 Scrapeless 仪表板获取的 Scrapeless API 密钥。
• 一个项目文件夹，用于存放配置文件。这里的测试使用了一个 Git 仓库。

第一步：将 .warp/.mcp.json 添加到您的项目

在项目根目录下创建 .warp/.mcp.json：

{
  "mcpServers": {
    "scrapeless": {
      "url": "https://api.scrapeless.com/mcp",
      "headers": {
        "x-api-token": "${SCRAPELESS_API_KEY}"
      }
    }
  }
}

一个 URL 服务器在 Warp 中需要两个属性：url，这是必需的，以及 headers，一个一般情况下是可选的键值对象，但在这里是必需的，因为 Scrapeless 通过 x-api-token 头部对每个请求进行身份验证。没有 type 字段可供设置。

该文件保存的是一个变量引用，而不是一个钥匙，因此它可以在版本控制中存在。每个打开项目的人会导出自己的密钥。这样可以将凭据排除在代码库之外，这被 OWASP 秘密管理指南 视为不应存放秘密的地方。

第 2 步：导出具有正确占位符的密钥

在启动 Warp 的 shell 中导出变量，然后从项目文件夹启动 CLI：

export SCRAPELESS_API_KEY="your-scrapeless-api-key"
cd path/to/your-project
warp

当 Warp 从磁盘读取配置文件时，会扩展 ${VAR} 引用。格式很重要，错误的格式静默失败。以下每个变体都通过本地日志代理进行发送，以查看实际到达 Scrapeless 的内容：

第二和第三行是陷阱。它们看起来就像工作设置，直到代理的第一次工具调用返回身份验证失败。

未导出的情况很明显，但它的影响远超一个服务器。Warp 拒绝整个文件，并在其定义的每个服务器所在的位置列出一个错误行：

Warp config error  /path/to/your-project/.warp/.mcp.json · Missing or empty environment variable: SCRAPELESS_API_KEY

在测试中，第二个有效服务器也从同一文件的列表中消失。请在你的 shell 配置文件中导出变量，或在任何启动你的终端会话的地方，以便每个 warp 进程都能继承它。

现在要设置这个吗？Scrapeless 免费计划 包括连接和你第一次工具调用的费用。

第 3 步：从 /mcp 启动服务器

在 CLI 输入中输入 /mcp 以打开 MCP 管理视图，然后在其搜索框中输入 scrapeless。该行会显示提供者标签、项目和传输：

scrapeless  Warp · scrapeless-demo · HTTP/SSE · offline

按 Enter 键在该行上。几秒钟后，Warp 运行 MCP 握手，列出工具并更新该行：

scrapeless  Warp · scrapeless-demo · HTTP/SSE · running · 25 tools

在运行的行上按 Enter 将停止服务器。由于项目范围的服务器是会话范围的，因此每次在该项目中打开 CLI 时请重复此启动。

第 4 步：在提示之前读取状态

/mcp 中的每个状态指向不同的修复：

failed 行值得更仔细看看，因为它的建议是偏离原因的。以 Authorization: Bearer ${SCRAPELESS_API_KEY} 作为头部，Warp 日志：

[error] MCP: Failed to connect to server: Transport creation error: MCP server 'scrapeless' rejected the configured credentials (HTTP 401). The request included the credential header(s) you configured, so the server did not accept that value — check the token itself, its expiry, and its scope. The server did not ask for OAuth.

该请求中的令牌是有效的。Scrapeless 拒绝了请求，因为头部名称错误，并且其响应正文说明了这一点：Unauthorized: Missing x-api-token header。更改头部名称并保持密钥不变。

Warp 在 Linux 上为每次服务器启动写一个日志文件，位于 ${XDG_STATE_HOME:-$HOME/.local/state}/warp-terminal/mcp。每个文件开头都有一个提醒，可能包含 API 密钥等敏感信息，因此请在本地阅读并在共享之前进行删减。

第 5 步：验证密钥，然后提示代理

一个运行的服务器有 25 个工具仅显示一个头部到达。Scrapeless 对任何密钥值，包括虚构的密钥，响应 initialize 和 tools/list。区别在于 tools/call：使用错误的密钥调用仍然返回 HTTP 200，结果文本以 Failed to fetch data 开头。

此检查运行与 Warp 相同的握手，然后调用 scrape_markdown 一次，仅使用 Python 标准库中的内容：

import json
import os
import urllib.request

URL = "https://api.scrapeless.com/mcp"
HEADERS = {
    "Content-Type": "application/json",
    "Accept": "application/json, text/event-stream",
    "x-api-token": os.environ["SCRAPELESS_API_KEY"],
}


def post(payload, session_id=None):
    headers = dict(HEADERS)
    if session_id:
        headers["Mcp-Session-Id"] = session_id
    request = urllib.request.Request(URL, data=json.dumps(payload).encode(), headers=headers)
    with urllib.request.urlopen(request, timeout=120) as response:
        body = response.read().decode()
        session_id = response.headers.get("Mcp-Session-Id") or session_id
    events = [line[5:].strip() for line in body.splitlines() if line.startswith("data:")]
    return session_id, json.loads(events[-1]) if events else None


session, init = post({
    "jsonrpc": "2.0", "id": 1, "method": "initialize",
    "params": {"protocolVersion": "2025-06-18", "capabilities": {},
               "clientInfo": {"name": "key-check", "version": "1.0"}},
})
post({"jsonrpc": "2.0", "method": "notifications/initialized"}, session)
_, result = post({
    "jsonrpc": "2.0", "id": 2, "method": "tools/call",
    "params": {"name": "scrape_markdown", "arguments": {"url": "https://example.com"}},
}, session)

server = init["result"]["serverInfo"]
text = "".join(part.get("text", "") for part in result["result"]["content"])
print(server["name"], server["version"])
if text.startswith("Failed to fetch data"):
    print("key rejected:", text[:60])
else:
    print(f"key accepted: {len(text)} characters of Markdown")

导出有效密钥后，会打印：

scrapeless-mcp-server 0.2.0
key accepted: 184 characters of Markdown

一旦密钥验证通过，给服务器和工具起名，当工作是单个抓取时：

注意：代理回合需要您 Warp 账户上的 AI 额度，但由于测试账户已没有额度，因此未对本文进行运行；Warp 回答“您已经用完了 AI 额度。”上述服务器启动、握手和密钥检查是针对相同端点和相同配置进行的。

Use the scrapeless MCP server's scrape_markdown tool to fetch
https://books.toscrape.com/catalogue/category/books/mystery_3/index.html
and list the first three book titles with their prices.

在该分类页面 scrape_markdown 返回 8,940 个字符，而 scrape_html 返回 53,800，因此 Markdown 使代理的上下文成本大约是相同内容的六分之一。当您自己的代码解析结果时，请使用 scrape_html，当代理读取它时，请使用 scrape_markdown。

MCP 工具调用遵循您当前的执行配置文件。 mcp_permissions 默认值为 agent_decides，而配置文件的 mcp_allowlist 和 mcp_denylist 接受可能无需批准或必须始终请求的 MCP 服务器 ID。

Scrapeless MCP 服务器公告 描述了服务器公开的内容，浏览器 MCP 文档 包含配置参考，抓取 API 页面介绍了工具背后的参与者，而 定价 列出了调用的费用。

结论

连接器是 .warp/.mcp.json 中的一个条目，有三个条件：标头命名为 x-api-token，其值为带花括号的 ${SCRAPELESS_API_KEY}，变量在启动 warp 的 shell 中导出。在此之后，每次会话从 /mcp 启动服务器。

有两个结果需要注意，因为它们看起来正常。错误的占位符形式和错误的密钥都显示 running · 25 tools，仅工具调用才能暴露它们。出现的失败的读取文本不同：Bearer 标头产生 failed … rejected the configured credentials，未导出的变量产生一个配置错误，隐藏文件中的每个服务器。

准备好为 Warp Agent 提供网络的实时视图吗？从 Scrapeless 免费计划开始 并添加服务器。

常见问题

问：如何通过 API 密钥头将远程 MCP 服务器添加到 Warp？

在项目根目录创建 .warp/.mcp.json，并具有 mcpServers 条目的 url 和 headers 对象，例如 "x-api-token": "${SCRAPELESS_API_KEY}"。导出变量，在该文件夹中启动 warp，然后从 /mcp 启动服务器。在 Warp 桌面应用程序中，在“设置 > 代理 > MCP 服务器 > + 添加”中粘贴相同的 JSON。

问：Warp 是否在 MCP 头部展开环境变量？

是的，以 ${VAR} 形式。${SCRAPELESS_API_KEY} 的标头值作为导出密钥到达服务器。没有花括号的 $SCRAPELESS_API_KEY 和 {{SCRAPELESS_API_KEY}} 作为文字文本发送。

问：为什么我的 Warp MCP 服务器显示运行有错误的 API 密钥？

running · 25 tools 意味着握手和工具列出有效，Scrapeless 对任何密钥值的响应都是有效的。错误的密钥仅在工具运行时才会显示：调用返回以 Failed to fetch data 开头的文本。

问：为什么 Warp 说 MCP 服务器拒绝了配置的凭据？

对于 Scrapeless，通常原因是标头名称，而不是令牌。Authorization: Bearer 标头会产生 rejected the configured credentials (HTTP 401)，因为服务器在寻找 x-api-token 并回答 Missing x-api-token header。

问：“Warp 配置错误…缺少或为空的环境变量”意味着什么？

文件引用了在启动 warp 的 shell 中未设置的变量。Warp 拒绝整个文件，因此定义在其中的每个服务器都从 /mcp 消失，直到您导出变量并再次启动 CLI。

问：项目范围的 MCP 服务器在 Warp 中自动启动吗？

不。Warp 在项目中检测到 .warp/.mcp.json、.mcp.json 和 .agents/.mcp.json，但将其服务器列为 offline，直到您从 /mcp 启动每个服务器，而该选择仅持续到当前会话。

问：为什么 Warp Agent CLI 不从 ~/.warp_cli/.mcp.json 列出我的服务器？

CLI 文档给出了 macOS 的路径。在 Linux 上，Warp Agent CLI v0.2026.09.09.08.26.stable_02 未读取 ~/.warp_cli/.mcp.json 或 ~/.warp/.mcp.json，而 /mcp 答复了 No matching MCP servers。项目文件 .warp/.mcp.json 被发现。

问：Scrapeless MCP 服务器向 Warp 添加了多少工具？
25: 三个 scrape_* 工具，十六个 browser_* 工具，三个 crawl_* 工具，加上 google_search，google_trends 和 ai_scraper。