Resolución de captchas para
agentes de MCP
Un agente que se encuentra con un desafío no tiene nada en su conjunto de herramientas que pueda responderlo, así que se atasca o alucina para sortearlo. Dale un solucionador como herramienta y el bloqueo se convierte en una llamada más.
# Claude Code
claude mcp add captchano -e CAPTCHANO_API_KEY=cn-YOUR_API_KEY -- npx -y captchano-mcp
# Claude Desktop / Cursor / VS Code (mcpServers config)
{
"mcpServers": {
"captchano": {
"command": "npx",
"args": ["-y", "captchano-mcp"],
"env": {
"CAPTCHANO_API_KEY": "cn-YOUR_API_KEY",
"CAPTCHANO_MAX_SPEND_USD": "1"
}
}
}
}
# Tools: solve_captcha · get_task · get_balance · list_captcha_types
# Source (MIT): https://github.com/DishantSinghDev2/captchano-mcpPor qué los agentes necesitan esto en concreto
Un scraper que se encuentra con un desafío falla de forma visible y lo arreglas. Un agente falla en silencio: razona sobre la página bloqueada, inventa un siguiente paso verosímil e informa de un progreso que nunca hizo. El fallo es peor porque es silencioso. Una herramienta de resolución tipada convierte un callejón sin salida ambiguo en un resultado determinista sobre el que el agente puede ramificar.
Qué devuelve la herramienta
- Un token o una cookie, según el tipo de desafío. Los sistemas que evalúan la sesión devuelven una cookie junto con el conjunto de encabezados usado para obtenerla.
- El user agent usado, para que el agente pueda reutilizarlo al enviar.
- El costo de la resolución, para que un agente que opera con un presupuesto pueda tenerlo en cuenta en lugar de gastar a ciegas.
Mantener el bucle acotado
Dale al agente un presupuesto de resoluciones por ejecución. Cada respuesta indica su costo, así que un supervisor puede cortar el bucle cuando el gasto supera un umbral en lugar de descubrirlo en la factura. A $0.00598 por resolución, una ejecución típica de un agente cuesta unos pocos centavos o menos, pero un bucle de reintentos sin límite sigue siendo un bucle de reintentos sin límite.
Mantén la llamada a la herramienta bloqueante
Los ejemplos llaman a ?wait=60, así que la herramienta devuelve un token terminado en un solo paso. Eso importa más en los agentes que en los scripts: una herramienta que devuelve "todavía resolviendo" obliga al modelo a razonar sobre el sondeo, algo que hace mal. Si necesitas un límite mayor, sube wait hasta 120 segundos. Las estructuras de solicitud de cada tipo de desafío están en la referencia de la API.
Cómo encaja la resolución en MCP
captchano-mcp es nuestro servidor MCP de código abierto: expone la resolución como herramientas que cualquier cliente MCP puede llamar, así que el agente supera un captcha con una sola llamada a una herramienta y recibe un token.
- 01Añade el servidor
Claude Code: claude mcp add captchano -e CAPTCHANO_API_KEY=cn-… -- npx -y captchano-mcp. Otros clientes usan el mismo comando npx en su configuración MCP.
- 02Fija un presupuesto
Opcionalmente, define CAPTCHANO_MAX_SPEND_USD para que el servidor rechace más resoluciones cuando la sesión haya gastado esa cantidad.
- 03Deja que el modelo la llame
Cuando el agente ve un desafío, llama a solve_captcha con el tipo, la sitekey y la URL; list_captcha_types le indica qué campos necesita cada tipo.
- 04Usa el token
El agente pasa el token a su herramienta de navegador para inyectarlo y enviar. Las resoluciones largas devuelven un ID de tarea que se consulta con get_task.
Cómo introducir el token en la página
El cliente recibe el token como resultado de la herramienta y se lo pasa a la herramienta de navegador que rellena la página.
Dónde suelen fallar las integraciones
Guarda la clave de API en el entorno del servidor, nunca en los argumentos de la herramienta, para que el modelo nunca la vea.
Mantén wait=60 para que la herramienta devuelva un token terminado en lugar de pedirle al modelo que consulte periódicamente.
Preguntas frecuentes sobre captchas en MCP
¿Existe un paquete MCP oficial de CaptchaNo?
Sí. captchano-mcp es nuestro servidor de código abierto (MIT), disponible en npm y en el MCP Registry oficial. Ejecútalo con npx -y captchano-mcp y tu clave en CAPTCHANO_API_KEY; la clave se queda en tu equipo y nunca es un argumento de la herramienta.
¿Con qué clientes MCP funciona?
Con cualquier cliente que admita herramientas MCP por stdio o HTTP, ya que el servidor solo expone una herramienta estándar.
¿Cómo encuentra el agente la sitekey?
Con su herramienta de navegador: lee el atributo data-sitekey o la URL de la página del desafío y se la pasa a la herramienta de resolución.
¿Puedo limitar lo que gasta el agente?
Sí. Cada resultado incluye el costo, así que el servidor puede llevar un total acumulado y rechazar más resoluciones al superar un presupuesto.
Guías útiles
¿Listo para construir?
Empieza con una prueba gratuita de 3 días y luego paga por cada resolución exitosa a medida que crece tu tráfico. No necesitas tarjeta para la prueba.