Composio + Scrapeless：添加自定义 MCP 工具包

TL;DR:

• Scrapeless不在Composio的工具包目录中，因此它作为一个自定义MCP工具包加入。 Composio的仪表盘具有一个添加自定义MCP对话框，标记为Beta，可以从远程MCP服务器创建一个。
• 该对话框需要四个值。 一个显示名称，服务器URL https://api.scrapeless.com/mcp，API密钥作为认证类型，以及x-api-token作为高级设置下的头部名称。
• 将头部前缀留空。 Scrapeless期望在x-api-token中仅有密钥。使用前缀如token时，握手和25个工具的列表仍然成功，但每个工具调用都会失败。
• Composio检查输入了密钥，而不是Scrapeless是否接受它。 在添加工具包之前检查密钥和头部值，并在之后通过一次工具调用确认。
• 该工具包属于一个Composio项目。 将其CUSTOM_短语添加到会话中，并将session.mcp.url传递给任何MCP客户端。
• 在Scrapeless免费计划上获取密钥，并在几分钟内添加工具包。

Composio会话为代理提供经过身份验证的工具，涵盖长列表应用，凭据保存在Composio一侧。会话不包括实时网络，例如页面的当前渲染或Google搜索的结果。Scrapeless MCP服务器将这些作为工具提供，Composio的自定义MCP功能允许会话在内置工具包旁调用它们。

本指南通过仪表盘对话框添加Scrapeless，然后在会话中使用该工具包。大部分工作是一个单一的表单。需要注意的部分是头部，因为错误的头部格式在实际运行工具之前看起来是连接的。

为什么Scrapeless作为自定义MCP工具包加入Composio

Composio的目录包含Composio发布的工具包，而Scrapeless不是其中之一。对于目录外的服务，Composio的自定义MCP指南描述了这条路径。你通过其公共HTTPS URL和认证方案注册一个远程MCP服务器，Composio创建一个与CUSTOM_短语关联的工具包，同步服务器的工具，并使用已连接账户的凭据代理每个工具调用。

这带来了三个限制。自定义MCP是实验性的，Composio表示其设置流程和契约可能会变化。该工具包的作用范围限于注册它的Composio项目。而且Composio不托管该服务器，因此服务器必须通过HTTPS可访问；Scrapeless是一个托管端点，因此没有任何在你的机器上运行。

同一指南仍然将注册描述为仅API，并将仪表盘管理列为即将推出。2026年9月的Composio仪表盘已经显示了一个添加自定义MCP对话框，标记为Beta和仅MCP，而该对话框正是本指南所遵循的路径。API路径在常见问题解答中有介绍。

Scrapeless为Composio会话添加了什么

该服务器暴露了25个工具，按工作分组：

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

所有25个工具作为一个工具包到达。在默认会话中，Composio的指南表示代理通过其工具搜索发现自定义工具，并通过工具路由器运行它们，方式与访问内置工具包相同。

先决条件

• 一个包含项目的Composio账户。自定义MCP工具包属于一个项目。
• 从Scrapeless仪表盘获取的Scrapeless API密钥。仅服务于Composio的密钥可以在不影响其他集成的情况下进行更换。
• 用于第1步检查的Python 3，只使用标准库。
• 对于第4步，Composio Python SDK（本指南使用的是composio 0.21.1）和你的Composio项目API密钥。本指南的第4步会话代码尚未在Composio项目上运行。

第1步：检查密钥和头部值

Composio的指南列出了一个值得注意的已知差距：当你连接API密钥服务器时，设置检查提供了密钥，而不是远程服务器是否接受它。Scrapeless增加了第二个盲点，因为它回答MCP握手并为任何密钥值列出其工具。错误的密钥或错误的头部格式只有在工具运行时才会显现。
这个脚本发送 MCP 客户端发送的请求，使用 x-api-token 头中的密钥，列出工具，然后调用 scrape_markdown 一次。它遵循 可流式传输的 MCP HTTP 传输，通过 POST 以 JSON-RPC 发送到单个端点，并且只需要 Python 标准库：

import json
import os
import urllib.request

URL = "https://api.scrapeless.com/mcp"
PREFIX = os.environ.get("HEADER_PREFIX", "")
HEADERS = {
    "Content-Type": "application/json",
    "Accept": "application/json, text/event-stream",
    "x-api-token": f"{PREFIX} {os.environ['SCRAPELESS_API_KEY']}".strip(),
}


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": "header-check", "version": "1.0"}},
})
post({"jsonrpc": "2.0", "method": "notifications/initialized"}, session)
_, listing = post({"jsonrpc": "2.0", "id": 2, "method": "tools/list"}, session)
_, result = post({
    "jsonrpc": "2.0", "id": 3, "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"])
print("tools listed:", len(listing["result"]["tools"]))
if text.startswith("Failed to fetch data"):
    print("key rejected:", text[:20])
else:
    print(f"key accepted: {len(text)} characters of Markdown")

导出您的密钥为 SCRAPELESS_API_KEY，它打印：

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

现在导出 HEADER_PREFIX=token 并再次运行。脚本在密钥前放置 token 和一个空格，形成一个带前缀的头值：

scrapeless-mcp-server 0.2.0
tools listed: 25
key rejected: Failed to fetch data

握手和工具计数在两次运行中是相同的。只有工具调用使它们区分开来，Bearer 作为前缀的调用同样失败。

步骤 2：使用自定义 MCP 添加 Scrapeless

在 Composio 仪表板中，打开 添加自定义 MCP，对话框标题为“从远程 MCP 服务器创建工具包”，并填写内容：

然后选择 添加。

头前缀是需要关注的字段。它存在于期望前置方案词的 API 之中，例如 Bearer。Scrapeless 将整个 x-api-token 值视为密钥，因此任何前缀都将有效密钥变成一个它拒绝的密钥，正如步骤 1 中的第二次运行所展示的那样。

在保存之前请务必正确设置这些参数。在 Composio 的 API 中，头格式是工具包身份验证方案的一部分，而自定义 MCP 指南指出，服务器 URL 和身份验证方案在注册后不得更改；尝试更改将返回 409 Conflict。要修复带前缀的已保存工具包，请在其页面上使用 删除 并再次添加它。删除自定义工具包还会删除其身份验证配置和连接的帐户，因此您需要在之后重新连接该帐户。

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

步骤 3：连接账户并让工具同步

一个 API 密钥工具包在账户连接之前没有任何可调用内容，这里就是密钥的位置。步骤 2 中的空头前缀仅意味着密钥前面没有任何内容。连接后会打开一个标题为“Composio 想要连接到您的”并接着是工具包名称的页面，上面有一个必填的 API 密钥 字段。将您的 Scrapeless API 密钥粘贴到那里，并选择 连接账户。Composio 将密钥存储在连接的帐户上，并将其放在每个发送给 Scrapeless 的请求的 x-api-token 头中。

一旦该账户变为活动状态，第一次同步将在后台启动。在 Scrapeless 页面上，连接的账户 列出该账户为 活动，并且 可用操作 下显示 25，分别对应每个 Scrapeless 工具，如 “Ai scraper” 和 “Browser click”。后续的连接不会再次同步工具包，因此当 Scrapeless 添加工具时，请在该页面使用 同步。一个自定义工具包最多可容纳 500 个工具。

一个同步的工具列表证明 Composio 已连接到服务器。它不证明密钥，因为步骤 1 显示了原因，这也是最后一步以工具调用结束的原因。

现在密钥也存在于第三方。OWASP 秘密管理指南 将密钥轮换视为常规操作，并且一个专门为 Composio 所用的密钥是可以轮换的，而不会破坏其他任何东西。

步骤 4：在会话中使用工具包

将工具包的标识符添加到会话中。使用 mcp=True，该会话还暴露了一个任何 MCP 客户端都可以使用的托管 MCP 服务器。

注意：此代码遵循 Composio Python SDK 0.21.1 和 Composio 的会话指南；它尚未针对本指南在 Composio 项目中运行。它需要 COMPOSIO_API_KEY 设置为您的项目 API 密钥。

from composio import Composio

composio = Composio()  # reads COMPOSIO_API_KEY from the environment

session = composio.sessions.create(
    user_id="user_123",
    toolkits=["CUSTOM_SCRAPELESS"],
    connected_accounts={"CUSTOM_SCRAPELESS": ["ca_your_connected_account_id"]},
    mcp=True,
)

print(session.mcp.url)

如果您工具包页面上显示的标识符与 CUSTOM_SCRAPELESS 不同，请使用所示的标识符；Composio 在注册工具包时会添加 CUSTOM_ 前缀。connected_accounts 条目固定用于调用的账户。会话仅在工具包的身份验证配置启用了工具路由匹配时，根据 user_id 匹配账户，而没有它，调用将以 NoActiveConnection 失败。固定账户的方式均有效。
Composio 关于通过 MCP 进行会话的指南 将 session.mcp.url 和 session.mcp.headers 传递给客户端的 MCP 配置，适用于 OpenAI Agents SDK 和 Claude Agent SDK 等框架。标题携带了该 URL 的凭证，因此请在不记录凭证的情况下将其交给客户端。

然后给代理一个可检查的工作：

Use the Scrapeless scrape_markdown tool to fetch https://example.com
and reply with the first heading of the returned page, quoted exactly.

一个有效的设置会回复 "# Example Domain"。一个引用 Failed to fetch data 的回复指向密钥或标题前缀。

修复常见问题

有关服务器公开的内容，阅读 Scrapeless MCP 服务器公告。 浏览器 MCP 文档 包含配置参考，抓取 API 页面覆盖了工具背后的参与者，以及 定价 列出了调用的费用。

结论

将 Scrapeless 添加到 Composio 只需一次对话：一个显示名称，https://api.scrapeless.com/mcp，API 密钥身份验证，x-api-token 作为标题名称以及一个空的标题前缀。使用您的密钥连接账户，让工具同步，然后将 CUSTOM_ 工具包添加到会话中。

需要注意的是，已同步和可工作之间的差距。Composio 确认已输入密钥，而 Scrapeless 列出任何密钥的工具，因此前缀错误会通过两个检查。在添加工具包之前运行密钥检查，并在之后运行一次真实的工具调用，这样设置就能被证明是完整的。

准备好让您的 Composio 代理实时查看网络了吗？ 从 Scrapeless 免费计划开始 并添加工具包。

常见问题

问：我可以将自定义 MCP 服务器添加到 Composio 吗？

可以。自定义 MCP 通过其 HTTPS URL 和身份验证方案注册远程服务器，并将其转换为项目范围的工具包，带有 CUSTOM_ 代码。仪表板有一个添加自定义 MCP 的对话框，Composio 的 API 通过其自定义工具包端点提供相同的注册功能。

问：Scrapeless 的标题前缀中填写什么？

什么也不填写。将标题名称设置为 x-api-token 并保持前缀为空，因为 Scrapeless 将整个标题值读取为密钥。token 或 Bearer 前缀会导致每次工具调用失败，即使工具仍然能够同步。

问：我在 Composio 的哪里输入 Scrapeless API 密钥？

在连接页面，当您在工具包上连接账户时。添加自定义 MCP 对话框仅定义标题名称和前缀；连接页面要求输入 API 密钥，而 Composio 将该值作为 x-api-token 头部发送。

问：为什么我的 Scrapeless 工具在 Composio 中同步但每次调用都失败？

工具列表能够与任意密钥值一起工作，因此同步的工具包并不证明凭证的有效性。返回 Failed to fetch data 的调用意味着标题值错误：填写的标题前缀或无效的密钥。使用您的密钥运行第 1 步中的检查以查看是哪种情况。

问：我可以在添加工具包后更改标题设置吗？

不能就地更改。Composio 将服务器 URL 和身份验证方案视为注册后固定。删除工具包，再用正确的设置重新添加，并再次连接账户，因为删除会移除其连接。

问：我可以通过 Composio 的 API 注册 Scrapeless，而不是通过仪表板吗？
是的。POST /api/v3.1/custom/toolkits/upsert 接受服务器 URL 和 API_KEY 身份验证方案以及 headers 对象。Composio 允许使用除 Authorization 以外的头部名称，只要一个头部值包含 {{generic_api_key}}，因此 Scrapeless 的条目为 "x-api-token": "{{generic_api_key}}"。对于 API-key 服务器，指南在账户连接之前添加了一个单独的身份验证配置步骤。

问：Scrapeless 工具包在我所有的 Composio 项目中都可用吗？

不可以。自定义 MCP 工具包的范围限于注册它的项目。请在每个需要 Scrapeless 的项目中添加。

问：Claude、Cursor 或其他 MCP 客户端可以通过 Composio 使用 Scrapeless 吗？

可以。创建一个带有 mcp=True 的会话，并给予客户端 session.mcp.url 和 session.mcp.headers。客户端然后通过 Composio 会话访问 Scrapeless 工具。

问：Scrapeless 为 Composio 添加了多少个工具？

25 个：三个 scrape_* 工具，十六个 browser_* 工具，三个 crawl_* 工具，以及 google_search、google_trends 和 ai_scraper。