Périmètre sûr : ce guide s'applique uniquement à vos propres applications, à vos environnements de QA, de préproduction ou de production, ou à des systèmes pour lesquels vous disposez d'une autorisation écrite. Il ne décrit ni l'automatisation de sites tiers, ni la neutralisation de protections anti-bot, ni aucune forme d'évasion.
Un serveur MCP (Model Context Protocol) permet à Claude Desktop d'appeler des outils externes de manière structurée. En plaçant CaptchaAI derrière un tel serveur, vous donnez à votre agent la capacité de résoudre un défi CAPTCHA sans sortir de sa boucle de raisonnement : il transmet les paramètres, récupère un token, puis reprend son workflow. Ce guide montre comment câbler cette intégration pour qu'elle tienne en production, pas seulement le temps d'une démonstration.
Pourquoi exposer CaptchaAI comme un outil MCP
Claude Desktop ne sait pas résoudre un CAPTCHA seul, et il ne devrait pas essayer. Le rôle du serveur MCP est de lui offrir un outil clair — « résoudre ce défi » — dont l'implémentation, elle, appelle l'API CaptchaAI côté serveur. L'agent n'a jamais besoin de connaître votre clé API ni la mécanique du polling : il envoie un sitekey et une URL de page, il reçoit un token.
Ce découpage vous apporte trois avantages concrets :
- Une surface d'attaque réduite : le secret reste hors du contexte de conversation.
- Une seule intégration à maintenir : CaptchaAI expose une API homogène sur toutes les familles prises en charge (reCAPTCHA v2 et v3, Cloudflare Turnstile et Challenge, GeeTest v3, image/OCR, grilles).
- Une facturation lisible, basée sur les threads, avec des résolutions illimitées par thread.
Le plan BASIC ($15/mois, 5 threads) suffit à la plupart des agents individuels ; vous montez en threads seulement quand la concurrence l'exige.
Architecture de l'intégration
Le flux comporte trois maillons. Claude Desktop appelle l'outil exposé par votre serveur MCP. Le serveur MCP, un processus que vous contrôlez, traduit cet appel en requête HTTPS vers CaptchaAI, attend le token, puis le renvoie à l'agent. L'agent injecte enfin ce token dans le formulaire ou la route d'API de votre propre application.
Tracez chaque maillon séparément : un identifiant de corrélation qui traverse les trois couches vous permet de rejouer un scénario complet à partir d'un seul log, précieux quand une montée de version casse un enchaînement. Pour une équipe francophone qui déploie ses workers sur OVHcloud ou Scaleway (région eu-west-3 à Paris), gardez le serveur MCP proche de l'application cible : la latence réseau compte autant que le temps de résolution.
Configuration des secrets et de la clé API
La clé CaptchaAI ne doit jamais apparaître dans le fichier de configuration de Claude Desktop ni dans un message de l'agent. Stockez-la dans un coffre (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault) ou dans un secret d'intégration continue, et laissez le déploiement la monter en variable d'environnement au démarrage du serveur MCP. Le processus MCP lit CAPTCHAAI_KEY au runtime.
Cette séparation rend aussi l'intégration défendable côté conformité : si votre agent collecte des données, minimisez ce que vous conservez et vérifiez vos obligations RGPD avant de journaliser des identifiants de session.
Exemple : l'outil de résolution côté serveur
Voici l'appel HTTP que le serveur MCP effectue en interne, dans votre propre service. La fonction crée une tâche Turnstile et renvoie l'identifiant que la couche de polling ira interroger :
import fetch from 'node-fetch';
const API_KEY = process.env.CAPTCHAAI_KEY;
export async function createTurnstileTask(siteKey, pageUrl) {
const res = await fetch('https://api.captchaai.com/createTask', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
clientKey: API_KEY,
task: {
type: 'TurnstileTaskProxyless',
websiteURL: pageUrl,
websiteKey: siteKey,
},
}),
});
const data = await res.json();
return data.taskId;
}
Le même contrat vaut pour les autres familles : vous changez le type de tâche, vous conservez la boucle envoi/interrogation. Un seul outil MCP couvre ainsi plusieurs types de CAPTCHA. Pour les détails d'un type précis, appuyez-vous sur le guide de résolution de reCAPTCHA v2 via l'API.
Observabilité et journalisation
Quel que soit le langage retenu, instrumentez chaque appel CAPTCHA pour obtenir des signaux exploitables. Ces métriques alimentent les mêmes tableaux de bord que ceux de votre application, ce qui vous laisse repérer une régression bien avant vos utilisateurs.
| Signal à tracer | Ce qu'il révèle |
|---|---|
| Durée totale d'obtention du token | La latence réelle vue par l'agent |
| Code de retour HTTP | Une erreur d'API distinguée d'une erreur applicative |
| Identifiant de tâche | La corrélation et la rejouabilité d'un incident |
| Taille de la file d'attente interne | La saturation des threads avant vos utilisateurs |
Séparez les journaux par environnement — développement, préproduction, production — et corrélez-les à votre traçage distribué (OpenTelemetry, par exemple). Distinguez toujours deux mesures que l'on confond trop souvent : la réussite de la résolution et la réussite du workflow. Un token obtenu n'est pas un parcours accepté ; l'écart entre les deux trahit un problème de session ou de paramètres.
Liste de contrôle avant la mise en production
- Le périmètre reste strictement limité à vos propres applications ou à des sources autorisées.
- La clé CaptchaAI vit dans un coffre ou un secret CI, jamais dans le fichier de configuration de Claude Desktop ni dans le code source.
- Le token est appliqué dans la même session — même contexte de navigateur, même client HTTP, même cookie jar — que celle qui a déclenché le défi.
- Une stratégie de retry idempotent, avec backoff exponentiel borné, gère les erreurs transitoires.
- Les durées d'appel et les codes de retour sont tracés pour chaque exécution et rejouables depuis votre intégration continue.
Sur ce dernier point, voyez l'intégration de la résolution CAPTCHA en CI et le test de l'endpoint API sur vos formulaires.
FAQ
Qu'est-ce qu'un serveur MCP et pourquoi le connecter à Claude Desktop ?
Le Model Context Protocol est une interface standard qui permet à Claude Desktop d'appeler des outils externes. En exposant CaptchaAI derrière un serveur MCP, vous transformez « résoudre un CAPTCHA » en une simple fonction que l'agent invoque au bon moment, sans jamais manipuler votre clé ni la logique de polling.
Faut-il communiquer ma clé API CaptchaAI à Claude Desktop ?
Non. La clé reste côté serveur MCP, chargée depuis une variable d'environnement au runtime. L'agent ne voit que le nom de l'outil et les paramètres qu'il envoie ; le secret ne transite jamais par le contexte de conversation.
Quels types de CAPTCHA l'agent peut-il résoudre par ce biais ?
Les familles prises en charge par CaptchaAI : reCAPTCHA v2 et v3, Cloudflare Turnstile et Challenge, GeeTest v3, image/OCR et grilles d'images. CaptchaFox, Friendly Captcha et Lemin sont disponibles en bêta. En revanche, hCaptcha, FunCaptcha et GeeTest v4 ne sont pas pris en charge à ce jour.
Cette intégration est-elle compatible avec le RGPD ?
Le protocole est neutre ; c'est votre usage qui l'est ou non. Limitez les paramètres transmis au strict nécessaire, minimisez les données personnelles journalisées et vérifiez votre base juridique avant toute collecte. Restez dans le cadre de QA sur des environnements autorisés.
Guides connexes
- Le démarrage rapide CaptchaAI
- La QA CAPTCHA sur des environnements autorisés
- Tester l'endpoint API sur vos formulaires
- Intégrer la résolution CAPTCHA en CI
- Résoudre reCAPTCHA v2 via l'API
Donnez à votre agent une méthode de résolution CAPTCHA reproductible et observable. – Obtenez votre clé CaptchaAI.
