Résolution de captcha pour
agents MCP
Un agent qui rencontre un défi n'a rien dans sa boîte à outils pour y répondre : il se bloque ou hallucine un contournement. Donnez-lui un solveur sous forme d'outil et le blocage devient un appel de plus.
# 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-mcpPourquoi les agents en ont particulièrement besoin
Un scraper qui tombe sur un défi échoue bruyamment, et vous le corrigez. Un agent échoue en silence : il raisonne sur la page bloquée, invente une étape suivante plausible et signale des progrès qu'il n'a jamais faits. L'échec est pire parce qu'il est silencieux. Un outil de résolution typé transforme une impasse ambiguë en un résultat déterministe sur lequel l'agent peut s'appuyer.
Ce que renvoie l'outil
- Un token ou un cookie, selon le type de défi. Les systèmes évalués sur la session renvoient un cookie ainsi que l'ensemble des en-têtes utilisés pour l'obtenir.
- Le user agent utilisé, pour que l'agent puisse le réutiliser lors de la soumission.
- Le coût de la résolution, pour qu'un agent soumis à un budget puisse le comptabiliser au lieu de dépenser à l'aveugle.
Garder la boucle bornée
Donnez à l'agent un budget de résolutions par exécution. Chaque réponse indique son coût : un superviseur peut donc couper la boucle quand les dépenses dépassent un seuil, plutôt que de le découvrir sur la facture. À $0.00598 par résolution, une exécution d'agent typique coûte quelques centimes ou moins, mais une boucle de nouvelles tentatives sans limite reste une boucle sans limite.
Gardez l'appel d'outil bloquant
Les exemples appellent ?wait=60, pour que l'outil renvoie un token finalisé en une seule étape. C'est plus important pour les agents que pour les scripts : un outil qui renvoie "résolution en cours" oblige le modèle à raisonner sur le polling, ce qu'il fait mal. Si vous avez besoin d'un délai plus long, augmentez wait jusqu'à 120 secondes. Les formats de requête de chaque type de défi figurent dans la référence de l'API.
Comment la résolution s'intègre à MCP
captchano-mcp est notre serveur MCP open source : il expose la résolution sous forme d'outils que n'importe quel client MCP peut appeler, si bien que l'agent franchit un captcha en un seul appel d'outil et récupère un token.
- 01Ajouter le serveur
Claude Code : claude mcp add captchano -e CAPTCHANO_API_KEY=cn-… -- npx -y captchano-mcp. Les autres clients utilisent la même commande npx dans leur configuration MCP.
- 02Définir un budget
Définissez éventuellement CAPTCHANO_MAX_SPEND_USD pour que le serveur refuse toute nouvelle résolution une fois ce montant dépensé pendant la session.
- 03Laisser le modèle l'appeler
Lorsque l'agent rencontre un défi, il appelle solve_captcha avec le type, la sitekey et l'URL ; list_captcha_types lui indique les champs nécessaires pour chaque type.
- 04Utiliser le token
L'agent transmet le token à son outil navigateur pour l'injecter et envoyer le formulaire. Les résolutions longues renvoient un ID de tâche à vérifier avec get_task.
Injecter le token dans la page
Le client reçoit le token comme résultat de l'outil et le transmet à l'outil navigateur qui remplit la page.
Là où les intégrations échouent le plus souvent
Conservez la clé API dans l'environnement du serveur, jamais dans les arguments de l'outil, pour que le modèle ne la voie jamais.
Gardez wait=60 pour que l'outil renvoie un token finalisé au lieu de demander au modèle de faire du polling.
FAQ captcha MCP
Existe-t-il un package MCP officiel CaptchaNo ?
Oui. captchano-mcp est notre serveur open source (MIT), disponible sur npm et dans le MCP Registry officiel. Lancez-le avec npx -y captchano-mcp et votre clé dans CAPTCHANO_API_KEY ; la clé reste sur votre machine et n'est jamais un argument d'outil.
Avec quels clients MCP fonctionne-t-il ?
Avec tout client qui prend en charge les outils MCP via stdio ou HTTP, puisque le serveur n'expose qu'un outil standard.
Comment l'agent trouve-t-il la sitekey ?
Grâce à son outil navigateur : il lit l'attribut data-sitekey ou l'URL de la page de défi et la transmet à l'outil de résolution.
Puis-je limiter les dépenses de l'agent ?
Oui. Chaque résultat inclut le coût : le serveur peut donc tenir un total cumulé et refuser toute nouvelle résolution au-delà d'un budget.
Guides utiles
Prêt à développer ?
Commencez par un essai gratuit de 3 jours, puis payez par résolution réussie à mesure que votre trafic augmente. Aucune carte requise pour l'essai.