如何将 CapSolver MCP 连接到 rtrvr 浏览器代理程序

简要说明

• rtrvr可以通过MCP调用外部CAPTCHA工具。 其工具系统接受流式HTTP或SSE服务器，并通过限定名称公开导入的工具。
• 使用令牌模式工具进行与会话绑定的浏览器操作。 它返回一个令牌而无需打开第二个浏览器，rtrvr负责原始标签页和应用特定的提交步骤。
• 不要混淆两个名为solve_captcha的工具。 rtrvr文档记录了一个内置的浏览器操作，而外部MCP服务器会导入一个单独的限定工具，例如capsolver.solve_captcha。
• 返回的令牌不代表浏览器任务成功。 需要验证同一标签页、预期的应用程序响应、重试限制和最终工作流状态。

将类型化挑战工具连接到rtrvr的介绍

rtrvr结合了Chrome扩展、云浏览器、API、MCP、CLI和SDK，用于代理驱动的浏览器操作。其工具调用层还可以连接外部MCP服务器，并通过聊天或可重用的JavaScript子例程调用其工具。CapSolver 适配此架构，作为您拥有或授权自动化的网站和测试环境的独立挑战处理服务。

本指南展示了两个文档接口实际支持的窄集成。rtrvr控制活动浏览器标签页。CapSolver MCP提供一个类型化令牌模式工具。一个小型rtrvr子例程验证请求，调用限定的MCP工具，并将结构化结果返回到工作流。最终页面更新仍然是应用特定的步骤，因为CAPTCHA令牌绑定到挑战上下文，而不是通用点击结果。

本指南不假设产品之间的官方原生合作。它也不声称CapSolver MCP可以附加到rtrvr的内部浏览器对象。而是使用rtrvr的公开外部工具合同和CapSolver的公开MCP工具模式。

rtrvr和CapSolver集成支持的内容

rtrvr的工具调用文档指出，用户可以通过URL连接MCP服务器，启用导入的工具，直接使用@toolname调用它们，并通过rtrvr.callTool(name, params)在自定义工具中组合它们。导入的MCP工具会保存为带有服务器前缀的名称，这在两个系统发布相同工具名称时非常重要。

CapSolver的 MCPP服务文档公开了五个工具：

对于已登录的rtrvr标签页，solve_captcha是实际的起点。基于浏览器的CapSolver MCP工具会启动自己的Playwright会话。它们不会接收rtrvr的当前标签页、cookies、本地存储或页面状态。这使得solve_on_page适用于独立的、授权的页面检查，但不是现有rtrvr会话的透明延续。

还有一个故意设计的命名冲突。rtrvr将solve_captcha记录为其内置的pageAction工具之一。CapSolver MCP发布了一个同名的短名称工具。连接外部服务器后，检查工具列表并调用其完整导入名称，通常为capsolver.solve_captcha。不要让规划器猜测你意图的是哪一个。

架构和责任边界

将集成保持在四层：

这种分离可以防止三种常见错误。首先，模型不会发明任务字段。其次，令牌响应不会被记录为完成的业务操作。第三，访问拒绝、登录墙、MFA提示或不支持的挑战不会被重复发送到求解器。

仅在您拥有或有权限测试或自动化的系统上使用此模式。将支付、身份验证、账户创建、私有数据访问和其他敏感工作流置于显式人工批准和适用服务规则之后。

步骤1：通过流式HTTP启动CapSolver MCP

rtrvr通过URL连接外部MCP服务器，而CapSolver MCP默认使用本地stdio。通过流式HTTP启动相同的服务器，以便rtrvr扩展可以访问它。

python -m venv .venv
source .venv/bin/activate
pip install capsolver-core
pip install capsolver-mcp

export CAPSOLVER_API_KEY="YOUR_CAPSOLVER_API_KEY"
capsolver-mcp --transport streamable-http --host 127.0.0.1 --port 8000

官方MCP Python SDK使用/mcp作为默认的流式HTTP路径，因此本地端点为：

http://127.0.0.1:8000/mcp

绑定到127.0.0.1可保持服务本地。--api-key选项或CAPSOLVER_API_KEY环境变量对CapSolver进行身份验证；它不是对任何可以访问MCP端口的人的身份验证层。不要直接将此命令绑定到公共接口。如果远程rtrvr环境必须访问它，请在经过身份验证的HTTPS后部署，限制允许的网络，保护API密钥在秘密存储中，并审查MCP服务器的来源和传输设置。

令牌模式工具不需要Playwright。仅在有单独授权用途时安装浏览器额外组件detect_captchas或solve_on_page：

pip install "capsolver-mcp[browser]"
playwright install chromium

步骤2：在rtrvr中连接并验证MCP服务器

打开rtrvr的工具部分，添加本地MCP URL，并仅启用工作流需要的工具。rtrvr文档支持流式HTTP、SSE和OAuth保护的MCP服务器。对于此本地设置，使用上一步的流式HTTP URL。

从两个非浏览器调用开始：

@capsolver.get_supported_captchas
@capsolver.get_balance

rtrvr连接服务器时分配确切的前缀。如果不同，请使用工具面板中显示的名称。自定义子例程也可以调用await rtrvr.listTools()并检查每个可用工具的名称、描述、参数模式和来源。

这些检查回答不同的问题。get_supported_captchas证明rtrvr发现了外部工具。get_balance证明MCP过程接收了有效的账户凭证。这两个检查都不能证明可以完成真实挑战，但它们在您花费时间调试浏览器流之前将配置失败与任务失败分开。

不要在rtrvr提示、页面记录、截图或仓库中放置真实API密钥。将其保留在MCP进程环境中。如果进程日志记录工具参数，请在保留日志前删除令牌、密钥、包含敏感查询参数的URL以及任何目标特定标识符。

领取您的CapSolver优惠码

立即提升您的自动化预算！
在充值CapSolver账户时使用优惠码 CAP26，每次充值可获得额外 5% 奖励 —— 无限制。
立即在您的 CapSolver仪表板 中领取

步骤3：添加确定性的rtrvr子例程

rtrvr自定义JavaScript工具可以通过rtrvr.callTool调用连接的MCP工具。以下子例程在返回令牌前执行四件事：验证URL、允许支持的挑战类型、发现限定的外部工具，并规范化失败状态。

const allowedTypes = new Set(["reCaptchaV2", "reCaptchaV3", "cloudflare"]);

function fail(state, message, details = {}) {
  return { ok: false, state, message, ...details };
}

if (!allowedTypes.has(captchaType)) {
  return fail("unsupported_challenge", `Unsupported type: ${captchaType}`);
}

const parsed = new URL(websiteUrl);
if (parsed.protocol !== "https:") {
  return fail("policy_block", "Only approved HTTPS targets are allowed");
}

const tools = await rtrvr.listTools();
const solver = tools.find((tool) =>
  tool.source === "mcp" &&
  (tool.name === "capsolver.solve_captcha" || tool.name.endsWith(".solve_captcha"))
);

if (!solver) {
  return fail("configuration_error", "CapSolver MCP solve_captcha was not found");
}

const result = await rtrvr.callTool(solver.name, {
  captcha_type: captchaType,
  website_url: websiteUrl,
  website_key: websiteKey,
  version: version || null,
  page_action: pageAction || null,
  min_score: minScore || null,
  invisible: invisible ?? null,
  enterprise: enterprise ?? null,
  cdata: cdata || null,
  timeout: 90,
  polling_interval: 5,
});

if (!result?.success || !result?.solution?.token) {
  return fail("solve_failed", result?.error || "No token returned", {
    errorCode: result?.error_code || null,
    httpStatus: result?.http_status || null,
  });
}

return {
  ok: true,
  state: "token_ready",
  captchaType: result.solution.captcha_type,
  token: result.solution.token,
  expiresAt: result.solution.expire_time || null,
};

在rtrvr中将captchaType、websiteUrl、websiteKey和可选字段定义为工具参数。示例故意不从任意页面中提取站点密钥或向未知应用程序注入令牌。对于您控制的测试应用，添加一个单独的适配器，从您的应用合同中读取确切的挑战参数，并通过支持的表单或服务器端点提交结果。

包含的本地测试覆盖了带有模拟rtrvr工具运行时的编排分支逻辑。实时握手仍需要rtrvr账户、活动浏览器设备或云上下文、CapSolver API密钥和授权测试页面。

步骤4：保持令牌绑定到原始浏览器状态

CAPTCHA解决方案是上下文敏感的。挑战类型、公共站点密钥、页面URL、操作名称、会话状态，有时甚至代理或用户代理数据可能影响目标应用是否接受结果。因此，浏览器工作流必须保留原始标签页，并以应用预期的方式提交返回的令牌。

使用类型化工作流状态而不是通用重试循环：

1. page_ready: 目标页面加载并验证其身份。
2. challenge_detected: 存在支持的挑战，参数来自可信页面证据。
3. solve_requested: 为该挑战实例创建了一个绑定的MCP调用。
4. token_ready: 服务返回了令牌，但尚未声称应用成功。
5. submitted: 应用特定的适配器在相同授权会话中提交了令牌。
6. accepted: 目标路由、API响应或页面状态确认成功。
7. review或stopped: 状态模糊、不支持、敏感或超出预算。

不要将solve_on_page作为此会话绑定流的快捷方式。当前CapSolver MCP实现为该工具打开一个新的无头Chromium页面，执行检测和填写，然后关闭浏览器。这是一个有效的独立操作，但它与rtrvr的扩展或云浏览器不同会话。仅在可以接受并明确授权单独会话时使用。

步骤5：验证应用结果

成功的MCP响应意味着工具返回了解决方案对象。它不意味着登录、表单提交、提取任务或浏览器任务完成。验证应在原始标签页上的rtrvr中进行。

至少进行三项检查：

• 标签页连续性： 标签页ID、主机和预期的工作流步骤仍与产生挑战的请求匹配。
• 应用接受： 文档路由、DOM状态或服务器响应确认应用接受了结果。
• 业务结果： 预期的授权任务完成，而没有静默切换页面、账户或记录。

如果页面再次显示相同的挑战，请在配置的尝试预算后停止。重复的挑战循环可能表明令牌过期、参数不匹配、代理或用户代理不一致、不支持的挑战变体或更广泛的访问策略决策。更多调用不会证明进展。

记录状态和错误代码，而不是秘密。有用的事件包含关联ID、时间戳、工具名称、挑战类型、目标主机、尝试次数、状态转换、延迟和最终应用结果。不要在普通日志中保留解决方案令牌或API密钥。

排查rtrvr MCP集成问题

生产检查清单

在超越测试页面之前，请确认以下所有内容：

• 目标和浏览器工作流已获得授权；
• 通过其经过认证的MCP名称选择CapSolver工具；
• 挑战参数来自可信的运行时证据，而非模型猜测；
• API密钥应存储在环境或密钥存储中；
• MCP端点应为本地或通过经过身份验证的HTTPS及网络控制保护；
• 令牌处理应与应用特定的提交分离；
• 每个挑战实例和工作流的重试次数应有限制；
• 日志应避免包含API密钥、解决方案令牌、敏感URL和私有页面数据；
• rtrvr需验证原始标签中的最终状态；
• 敏感账户、支付、身份和私有数据操作需要显式审查；
• 不支持或模糊的状态应安全停止。

此检查清单比添加另一个计划提示更为重要。大多数集成失败发生在浏览器状态、工具输入、服务输出和应用接受之间的边界。这些是运行时契约，而非语言模型推理问题。

结论

rtrvr提供了调用CapSolver MCP所需的外部工具接口，但可靠的集成比仅仅启用工具更为狭窄。通过流式HTTP启动CapSolver MCP，在rtrvr的工具面板中连接端点，使用非浏览器工具验证发现，并通过其经过认证的名称调用外部求解器。对于活动的rtrvr会话，使用令牌模式，并将页面提交和结果验证保留在原始浏览器工作流中。将独立浏览器工具视为独立会话，保留类型化证据，并在遇到不支持或模糊状态时停止。在授权的浏览器代理工作流中，CapSolver 提供了记录在案的挑战工具，而rtrvr仍负责浏览器上下文和最终应用成功。

将CAPTCHA处理添加到授权的rtrvr工作流中

在CapSolver MCP文档中查看已发布的五个工具，然后在rtrvr的工具面板中连接本地或正确保护的端点。使用CapSolver仪表板测试一个已批准的工作流，然后再扩展集成。

FAQ

问：rtrvr是否有原生的CapSolver集成？

经过审查的文档并未声称有原生的合作伙伴关系或内置的CapSolver提供者。本指南中的集成使用rtrvr的一般MCP工具连接和CapSolver的公共MCP服务器。

问：为何不调用简短名称solve_captcha？

rtrvr记录了一个具有该名称的内置浏览器操作，而CapSolver MCP也发布了相同的简短名称。为避免歧义，请使用工具面板中显示的经过认证的导入名称，例如capsolver.solve_captcha。

问：CapSolver MCP能否使用rtrvr中已打开的浏览器标签？

通过记录的MCP工具无法实现。令牌模式需要显式挑战参数并返回令牌，而浏览器模式工具会启动一个独立的Playwright浏览器。

问：是否应将本地MCP端口暴露到互联网？

不。请将其保留在本地主机上供本地使用。共享部署需要经过身份验证的HTTPS、网络限制、密钥管理、来源控制和显式的安全审查。

问：如何确认浏览器任务成功？

使用预期的路由、DOM状态、API响应和业务结果，在原始rtrvr标签中验证结果。仅返回令牌本身并非成功证据。