Cómo usar el servidor CapSolver MCP: Guía de configuración del Agente de IA

TL;DR

• El servidor MCP de CapSolver expone cinco herramientas documentadas: solve_captcha, detect_captchas, solve_on_page, get_balance y get_supported_captchas.
• Instala capsolver-core antes de capsolver-mcp, luego configura un cliente MCP para lanzar el comando capsolver-mcp con la clave de API en su entorno.
• Las herramientas del navegador requieren el complemento del navegador y Chromium; el modo de token puede ejecutarse sin navegador cuando se conozcan previamente el tipo de CAPTCHA, la URL de la página y la clave del sitio.
• Los agentes en producción necesitan reglas de hosts aprobados, un intento de recuperación limitado, registros con datos eliminados y una verificación a nivel de aplicación del éxito.

Introducción

La respuesta más segura sobre cómo usar el servidor MCP de capsolver es tratar el manejo de CAPTCHA como una herramienta de infraestructura estrecha, no como una nueva fuente de autoridad para el agente. CapSolver proporciona el servicio oficial capsolver-mcp, que encapsula capsolver-core y permite que los clientes de IA compatibles descubran herramientas de CAPTCHA documentadas. El agente luego puede recuperarse de interrupciones de reCAPTCHA v2, reCAPTCHA v3 incluyendo Enterprise, o Cloudflare Turnstile dentro de un flujo de trabajo autorizado del navegador. Su aplicación sigue teniendo el alcance, las credenciales, los límites de reintento y la afirmación empresarial final. Esta guía muestra la instalación real y la configuración JSON, explica cada herramienta y los límites de salida, y define condiciones de parada para un uso legal, razonable y responsable. No autoriza el acceso a datos privados, restringidos, sensibles o no autorizados.

Comprender las Tres Capas de CapSolver

Antes de decidir cómo usar el servidor MCP de capsolver, separa las capas del producto. La revisión de CapSolver para agentes de IA describe la arquitectura de capa de recuperación. capsolver-core realiza la detección y resolución, capsolver-agent adapta estos métodos a esquemas accesibles por el agente, y capsolver-mcp publica la misma capacidad a través de MCP.

La API del SDK principal documenta create_capsolver, detect, get_captcha_info, solve y solve_on_page. El adaptador de herramientas del agente documenta get_all_tools y create_executor. La guía del servicio MCP es la fuente de verdad para la instalación, transportes, configuración y las cinco herramientas MCP.

Elija MCP cuando el cliente ya hable MCP

Use el servidor MCP de CapSolver para clientes como Claude Desktop, Cursor, Cline, VS Code u otro host compatible. Use capsolver-agent cuando esté escribiendo el bucle de llamadas a funciones usted mismo. Use capsolver-core cuando Playwright o un servicio tenga el control total del flujo de trabajo y ningún modelo necesite esquemas de herramientas. Esta distinción evita adaptadores duplicados y hace más fácil mantener cómo usar el servidor MCP de capsolver.

Instalar los Paquetes Oficiales

La secuencia oficial instala primero el motor principal y luego el envoltorio MCP:

pip install git+https://github.com/capsolver-ai/capsolver-core.git
pip install git+https://github.com/capsolver-ai/capsolver-mcp.git

Para la detección del navegador y solve_on_page, instale el complemento del navegador y Chromium:

pip install "capsolver-mcp[browser] @ git+https://github.com/capsolver-ai/capsolver-mcp.git"
playwright install chromium

Estos comandos son la entrada verificada para cómo usar el servidor MCP de capsolver. Una salida exitosa es un comando ejecutable capsolver-mcp. Deténgase si la instalación resuelve a un nombre de paquete no oficial, si el comando falta o si Chromium no está disponible para una implementación en modo navegador.

Configurar el Cliente MCP

La configuración oficial de stdio es compacta y funciona en muchos clientes locales MCP:

{
  "mcpServers": {
    "capsolver": {
      "command": "capsolver-mcp",
      "env": {
        "CAPSOLVER_API_KEY": "SU_CLAVE_API"
      }
    }
  }
}

Mantén la clave real en un gestor de secretos o en el entorno del cliente, en lugar de en el control de código fuente. La entrada es el comando y el entorno. La salida es un servidor conectado cuya lista de herramientas se puede inspeccionar. La condición de parada es un lanzamiento fallido, una ruta de ejecutable inesperada o un registro incompleto. El Especificación de herramientas MCP explica por qué los clientes deben descubrir y validar los esquemas de herramientas antes de las llamadas.

Verificar los nombres exactos de las herramientas

Después de recargar el cliente, confirme los cinco nombres: solve_captcha, detect_captchas, solve_on_page, get_balance y get_supported_captchas. El artículo sobre corrección de errores de CAPTCHA en un servidor MCP proporciona un camino de diagnóstico útil, mientras que recuperación de puntos de control del agente MCP explica por qué la recuperación debe permanecer limitada.

Canjea tu código promocional de CapSolver

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

Definir Entradas, Salidas y Condiciones de Parada

En modo token, el agente proporciona un tipo de CAPTCHA compatible, la URL de la página autorizada y la clave del sitio pública; solve_captcha devuelve una solución a través del resultado de la herramienta MCP. En modo navegador, detect_captchas lista los tipos detectados y solve_on_page realiza la detección, resolución y relleno documentados. get_balance informa sobre el balance, y get_supported_captchas informa sobre el registro actual.

No infiera éxito a partir de una respuesta de herramienta sin error. La aplicación debe verificar que la ruta, el estado del formulario o la afirmación de prueba esperada haya cambiado en la misma sesión del navegador. Detenga cómo usar el servidor MCP de capsolver después de un intento autónomo, un cambio de hostname, un segundo punto de control, autorización caducada, tipo de CAPTCHA no compatible o estado de página ambiguo.

La guía de configuración de CAPTCHA MCP ayuda a conectar la configuración con el descubrimiento real de herramientas. Para el comportamiento específico de reCAPTCHA en MCP, el ejemplo de reCAPTCHA v2 de Cursor muestra cómo una integración estrecha de cliente difiere de una implementación de servidor general.

Agregar Barreras de Seguridad para Producción

Una implementación en producción de cómo usar el servidor MCP de capsolver debe permitir solo hosts aprobados y acciones declaradas. Mantén cookies y credenciales fuera de los mensajes del modelo. Registra identificadores de solicitud, nombres de herramientas, estados terminales y códigos de error eliminados en lugar de tokens sin procesar. La guía de registro de OWASP apoya el diseño de eventos conscientes de privacidad, y la Marco de Gestión de Riesgos de IA de NIST apoya controles responsables.

Prueba claves faltantes, dependencias de navegador faltantes, descubrimiento incompleto de herramientas, tipos no compatibles, estado de página inalterado y desafíos repetidos. Cada caso negativo debe devolver un estado de revisión terminal en lugar de otra llamada autónoma.

Conclusión

El método práctico para cómo usar el servidor MCP de capsolver es sencillo: instale capsolver-core y capsolver-mcp, configure el comando oficial, verifique las cinco herramientas y coloque una puerta de autorización estricta delante de cada llamada. Trate el éxito de la aplicación como el resultado y la finalización de la herramienta como evidencia. Los equipos que operan flujos de trabajo de agentes de IA permitidos pueden evaluar CapSolver como la capa de infraestructura de CAPTCHA.

Preguntas Frecuentes

¿Soporta el servidor MCP de CapSolver todos los tipos de tareas de CapSolver para agentes?

No. La documentación actual de agentes de IA limita esta capa a reCAPTCHA v2, reCAPTCHA v3 incluyendo Enterprise y Cloudflare Turnstile. Consulte get_supported_captchas en tiempo de ejecución.

¿Qué comando debe lanzar un cliente MCP?

Use el ejecutable oficial capsolver-mcp, o lance el módulo instalado con Python del entorno cuando el ejecutable no esté en el PATH del cliente.

¿Cuándo requiere cómo usar el servidor MCP de capsolver a Playwright?

La detección del navegador y solve_on_page requieren el complemento del navegador y Chromium. El modo de token no requiere navegador cuando los parámetros de la página ya se conozcan.

¿Qué debe detener a un agente de IA después de una llamada a CAPTCHA?

Deténgalo ante un cambio de alcance, tipo no compatible, contexto de navegador faltante, desafío repetido, autorización caducada o estado de aplicación inalterado tras un intento.