Solucionador de CAPTCHA MCP: Guía de Integración de Cloudflare Turnstile

TL;DR

• Una herramienta MCP CAPTCHA debe estar detrás de una verificación de autorización, no ejecutarse automáticamente en cada error de navegador.
• CapSolver documenta un servicio MCP para clientes compatibles y un ciclo de vida de tarea construido alrededor de la creación de tareas y la recuperación de resultados.
• Un flujo de trabajo de Turnstile requiere la URL de la página y la clave del sitio, además de la consistencia de la sesión del navegador cuando la tarea documentada lo requiera.
• Trate los tokens devueltos como secretos de corta duración: evite los registros, use reintentos limitados y verifique el resultado de la página.
• La capacidad técnica no otorga permiso para acceder a datos privados, restringidos, sensibles o no autorizados.

Lo que permite la integración de MCP

Una integración de solucionador de Cloudflare Turnstile de MCP proporciona a un cliente de IA un límite de herramienta controlado para manejar un desafío en un flujo de trabajo autorizado. CapSolver documenta capsolver-mcp como una opción para clientes compatibles con MCP, mientras que su guía para agentes de IA separa la detección local y el relleno de respuestas de la reconocimiento realizado por el servicio.

El objetivo de diseño útil es la recuperación, no el acceso no restringido. Su agente detecta un paso bloqueado, verifica el alcance, compone los parámetros documentados, llama a una herramienta, verifica el resultado devuelto y continúa o detiene para revisión.

Requisitos previos y puerta de política

Antes de conectar la herramienta, defina dominios aprobados, acciones permitidas, intentos máximos, reglas de registro y una condición de revisión humana. El cliente también necesita el entorno de ejecución de MCP respaldado por su host y una credencial de CapSolver almacenada en un almacén de secretos; nunca coloque una credencial real en prompts o control de código fuente.

Cloudflare explica que un widget de Turnstile produce un token que el sitio valida del lado del servidor, por lo que un token en sí mismo no es prueba de que la acción comercial tenga éxito. Consulte el flujo de implementación de Turnstile y visión general de Turnstile de Cloudflare para el modelo del defensor.

Conectar el servicio MCP

Use el paquete y configuración actual mostrados en la documentación oficial del CapSolver Core SDK. El comando exacto de instalación no se duplica intencionalmente aquí porque las ubicaciones de paquetes y clientes compatibles pueden cambiar. Después de la instalación, confirme que el cliente enumera las herramientas de CapSolver esperadas, luego desconéctese limpiamente antes de colocar la configuración en un entorno compartido.

Este artículo no ejecutó un intercambio de credenciales. Ese test sigue siendo una brecha de requisito discierto; no se presenta ningún resultado de herramienta como evidencia en vivo.

Canjear su código de bonificación de CapSolver

¡Aumente su presupuesto de automatización de inmediato!
Use el código de bonificación CAP26 al recargar su cuenta de CapSolver para obtener un 5% adicional en cada recarga — sin límites.
Canjéalo ahora en tu Panel de CapSolver

Adjuntar la herramienta a un bucle de agente

Mantenga el contrato frente al modelo estrecho. Las entradas deben identificar la página aprobada y los parámetros del desafío; las salidas deben exponer el estado y un resultado opaco sin repetir credenciales. El agente nunca debe inventar una clave de sitio, tipo de tarea o respuesta de éxito.

Un bucle robusto tiene cinco estados: detected, authorized, submitted, verified y stopped. Mueva a verified solo después de que el navegador observe el estado de página esperado. Si la tarea sigue procesándose, consulte dentro de un presupuesto fijo basado en el ciclo de vida de la tarea de CapSolver. Deténgase en errores repetidos en lugar de crear un bucle de reintentos ilimitado.

Límites de fallos y observabilidad

Separe los errores de configuración de los fallos en el desafío. Los parámetros faltantes deben fallar antes de cualquier llamada a la API. Un error de servicio debe conservar un identificador de correlación pero redactar la credencial y el token devuelto. Una discrepancia del navegador debe preservar una captura de pantalla o una afirmación del DOM solo cuando esa evidencia no contenga datos sensibles.

Para el contexto del protocolo, la introducción oficial de MCP describe el límite cliente-servidor. Ese límite es útil para la aplicación de políticas porque el agente puede ser denegado el acceso a la herramienta a menos que la solicitud cumpla con su lista de permitidos.

Configuración del solucionador de CAPTCHA de MCP desde el SDK oficial

El servicio MCP de CapSolver se basa en el mismo SDK principal utilizado por integraciones directas de Python. Instale el paquete habilitado para navegador solo en un entorno aislado, luego exponga la herramienta a través de la configuración de su cliente MCP. El paquete oficial se instala actualmente desde GitHub en lugar de 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

Almacene CAPSOLVER_API_KEY en el almacén de secretos aprobado del host. No coloque el valor en el JSON de MCP, artículo, repositorio de código fuente o argumentos visibles para el modelo. La herramienta debe aceptar una referencia de página o información de desafío estructurada, mientras que el host inyecta credenciales fuera del contexto del modelo.

Use una política estricta de herramientas

Un host de MCP puede evaluar un objeto de política antes de la ejecución. La siguiente configuración es una política de aplicación ilustrativa, no un cargador de API de CapSolver:

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

Valide este archivo con su cargador de configuración al inicio. Rechace campos desconocidos para que un error de escritura no desactive silenciosamente un control.

Fallback de API directa de Turnstile

Cuando su aplicación ya conozca la URL del sitio y la clave del sitio, CapSolver documenta AntiTurnstileTaskProxyLess. Los campos necesarios de la tarea son type, websiteURL y websiteKey; metadata.action y metadata.cdata son opcionales cuando esos valores existen en el widget.

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("La tarea de Turnstile excedió el presupuesto de sondeo")

El código se comprueba sintácticamente pero no se ejecuta con credenciales en este artículo. Aplique el token devuelto solo dentro del mismo flujo de trabajo autorizado, luego verifique el estado de la página resultante.

Construir un camino de recuperación revisable

La mejor ruta de recuperación de MCP es lo suficientemente pequeña como para auditar: un dominio aprobado, un tipo de tarea documentado, un presupuesto de reintentos y una afirmación de página. Amplíe la cobertura solo después de que los registros muestren por qué ocurren los fallos. Revise la FAQ de CapSolver y los artículos relacionados de automatización al planificar el soporte operativo.

Para flujos de trabajo de agentes autorizados, CapSolver puede ser el componente de reconocimiento, mientras que su aplicación sigue siendo responsable de la autorización, el manejo de sesiones, la validación y la detención de forma segura.

Preguntas frecuentes

P: ¿MCP resuelve por sí mismo Cloudflare Turnstile?

No. MCP define un patrón de conexión de herramienta; el servicio configurado de CapSolver realiza el reconocimiento mientras que el cliente controla la detección, los parámetros y el uso del resultado.

P: ¿El agente puede llamar a la herramienta en cualquier sitio web?

No. Limitar las llamadas a sitios y acciones para las que tenga autorización para automatizar, y detenerse cuando el permiso sea incierto.

P: ¿Qué demuestra que el flujo tuvo éxito?

El navegador debe observar el estado de la página posterior a la verificación esperada; un token devuelto por sí mismo es insuficiente.

P: ¿Deben aparecer los tokens en los registros?

No. Trate las credenciales y los tokens devueltos como secretos y registre solo metadatos operativos redactados.