MCP 验证码破解器：Cloudflare Turnstile 集成指南

简要说明

• MCP验证码工具应置于授权检查之后，而不是在每次浏览器错误时自动运行。
• CapSolver记录了兼容客户端的MCP服务以及围绕任务创建和结果检索构建的任务生命周期。
• Turnstile工作流需要页面URL和站点密钥，当文档要求时需保持浏览器会话一致性。
• 将返回的令牌视为短期秘密：避免记录日志，使用有限重试，并验证页面结果。
• 技术能力不意味着有权访问私人、受限、敏感或未经授权的数据。

MCP集成的功能

MCP Cloudflare Turnstile求解器集成为AI客户端提供了一个受控工具边界，用于在授权工作流中处理挑战。CapSolver将capsolver-mcp记录为MCP兼容客户端的一个选项，其AI代理指南将本地检测和回填与服务执行的识别区分开来。

有用的设计目标是恢复，而不是无限制浏览。您的代理检测到被阻止的步骤，检查范围，组装文档参数，调用一个工具，验证返回的结果，然后继续或停止以进行审查。

先决条件和策略门

在连接工具之前，定义批准的域名、允许的操作、最大尝试次数、日志规则和人工审查条件。客户端还需要其主机支持的MCP运行时和存储在秘密存储中的CapSolver凭证；切勿将真实凭证放在提示或源代码控制中。

Cloudflare解释说，Turnstile小部件生成一个令牌，该令牌由网站在服务器端验证，因此令牌本身并不能证明业务操作成功。请参阅Cloudflare的 Turnstile实现流程 和 Turnstile概述 以了解防御者端模型。

连接MCP服务

使用官方CapSolver Core SDK文档中显示的当前包和配置。确切的安装命令有意未在此重复，因为包位置和支持的客户端可能会更改。安装后，确认客户端列出了预期的CapSolver工具，然后在将配置放入共享环境之前干净地断开连接。

本文未执行凭据握手。该测试仍然是一个已披露的先决条件缺口；不提供任何实时证据作为工具输出。

领取您的CapSolver优惠码

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

将工具连接到代理循环

保持面向模型的合同狭窄。输入应识别批准的页面和挑战参数；输出应暴露状态和不透明结果，而不要回显凭证。代理不应发明站点密钥、任务类型或成功响应。

一个健壮的循环有五个状态：detected、authorized、submitted、verified 和 stopped。只有在浏览器观察到预期的页面状态后，才能进入 verified。如果任务仍在处理中，请根据 CapSolver任务生命周期 在固定预算内轮询。在重复错误时停止，而不是创建无限制的重试循环。

失败边界和可观测性

将配置错误与挑战失败分开。缺少参数应在任何API调用之前失败。服务错误应保留相关标识符，但隐藏凭证和返回的令牌。浏览器不匹配时，仅在证据中不包含敏感数据时保留截图或DOM断言。

为了协议上下文，官方MCP介绍 描述了客户端-服务器边界。该边界对于策略执行是有用的，因为代理在请求符合您的允许列表之前可以被拒绝访问工具。

从官方SDK设置MCP验证码求解器

CapSolver的MCP服务基于与直接Python集成相同的Core SDK。仅在隔离环境中安装浏览器支持的包，然后通过MCP客户端的配置公开工具。官方包目前从GitHub而不是PyPI安装：

python -m venv .venv
source .venv/bin/activate
pip install "capsolver-core[playwright] @ git+https://github.com/capsolver-ai/capsolver-core.git"
playwright install chromium

将 CAPSOLVER_API_KEY 存储在主机的批准秘密存储中。不要将值放在MCP JSON、文章、源代码仓库或模型可见的参数中。工具应接受页面引用或结构化的挑战信息，而主机在模型上下文之外注入凭证。

使用严格的工具策略

MCP主机可以在分派前评估策略对象。以下配置是示例应用程序策略，不是CapSolver API负载：

{
  "allowedDomains": ["staging.example.com"],
  "allowedCaptchaTypes": ["cloudflare"],
  "maxAttempts": 2,
  "timeoutSeconds": 120,
  "requireHumanReviewForStateChange": true,
  "logToken": false
}

在启动时使用配置加载器验证此文件。拒绝未知字段，以免拼写错误静默禁用控制。

直接Turnstile API回退

当您的应用程序已经知道站点URL和站点密钥时，CapSolver记录了 AntiTurnstileTaskProxyLess。所需的任务字段是 type、websiteURL 和 websiteKey；当这些值存在于小部件上时，metadata.action 和 metadata.cdata 是可选的。

import os
import time
import requests

API = "https://api.capsolver.com"

def solve_turnstile(website_url: str, website_key: str) -> str:
    client_key = os.environ["CAPSOLVER_API_KEY"]
    create = requests.post(
        f"{API}/createTask",
        json={
            "clientKey": client_key,
            "task": {
                "type": "AntiTurnstileTaskProxyLess",
                "websiteURL": website_url,
                "websiteKey": website_key,
            },
        },
        timeout=30,
    ).json()
    if create.get("errorId"):
        raise RuntimeError(create.get("errorDescription", "createTask failed"))

    task_id = create["taskId"]
    deadline = time.monotonic() + 120
    while time.monotonic() < deadline:
        result = requests.post(
            f"{API}/getTaskResult",
            json={"clientKey": client_key, "taskId": task_id},
            timeout=30,
        ).json()
        if result.get("errorId"):
            raise RuntimeError(result.get("errorDescription", "getTaskResult failed"))
        if result.get("status") == "ready":
            return result["solution"]["token"]
        time.sleep(3)
    raise TimeoutError("Turnstile task exceeded the polling budget")

该代码经过语法检查，但本文中未运行凭据。仅在相同的授权工作流中使用返回的令牌，然后验证结果页面状态。

构建可审查的恢复路径

最佳的MCP恢复路径应小到可以审计：一个批准的域名，一个文档化任务类型，一个重试预算和一个页面断言。在日志显示失败原因后才扩展覆盖范围。在规划操作支持时，查阅 CapSolver常见问题 和相关 自动化文章。

对于授权代理工作流，CapSolver 可以作为识别组件，而您的应用程序仍负责权限、会话处理、验证和安全停止。

常见问题

Q: MCP本身是否解决Cloudflare Turnstile？

不。MCP定义了一个工具连接模式；配置的CapSolver服务执行识别，而客户端控制检测、参数和结果使用。

Q: 代理可以在任何网站上调用工具吗？

不。将调用限制在您被授权自动化的网站和操作上，当权限不明确时停止。

Q: 什么证明工作流成功？

浏览器必须观察到预期的验证后页面状态；仅返回的令牌本身是不够的。

Q: 令牌应出现在日志中吗？

不。将凭证和返回的令牌视为秘密，并仅记录脱敏的操作元数据。