Périmètre sûr : Ce guide s'applique exclusivement à vos propres applications, 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 le contournement de protections, ni l'évasion d'anti-bot.
Un serveur MCP CaptchaAI transforme la résolution de CAPTCHA en un outil que vos agents IA appellent directement depuis Cursor ou Windsurf, sans quitter l'éditeur. Le vrai enjeu n'est pas de faire fonctionner l'appel une fois dans un notebook, mais de le rendre assez stable pour tourner sans surveillance en CI, dans un cron ou derrière une file d'attente interne. Ce guide couvre l'architecture, les secrets, l'observabilité et le dépannage d'une intégration de production.
À quoi sert un serveur MCP CaptchaAI dans l'éditeur
Model Context Protocol (MCP) permet à un agent embarqué dans Cursor ou Windsurf d'invoquer des outils externes de façon structurée. En exposant CaptchaAI derrière un petit outil MCP, votre agent demande un token pour une étape protégée par un défi CAPTCHA, puis poursuit le workflow — génération de tests, vérification de bout en bout, collecte de données autorisée — sans intervention manuelle.
L'agent reste ainsi dans son contexte de travail, tandis que l'appel réseau passe par un composant que vous contrôlez, tracez et versionnez, et qui isole votre clé API du reste de la chaîne.
Architecture cible
Votre composant interne — l'outil MCP — appelle CaptchaAI via HTTPS pour récupérer un token, puis l'injecte dans votre formulaire, votre route d'API ou votre contexte de navigateur. Tracer chaque étape facilite la détection de régressions lors des montées de version.
Gardez le composant sans état : il reçoit une requête, obtient un token et le renvoie. Pour un déploiement francophone, logez-le sur un worker proche de vos utilisateurs — instance OVHcloud, Scaleway ou région AWS eu-west-3 (Paris) — afin de limiter la latence réseau ajoutée à celle de la résolution.
Configuration des secrets
La clé CaptchaAI vit dans un coffre (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault) ou dans un secret CI. Le déploiement la monte en variable d'environnement au runtime, jamais dans le code source ni dans un fichier de configuration versionné.
Séparez les clés par environnement. La facturation étant basée sur les threads — à partir du plan BASIC ($15/mois, 5 threads), chaque plan inclut des résolutions illimitées par thread —, isoler la préproduction de la production protège directement votre solde et simplifie la rotation en cas de fuite.
Exemple de code
Exemple d'appel HTTP côté serveur dans votre propre service :
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 contrat reste le même quel que soit le type de défi : vous soumettez une tâche, récupérez un identifiant, puis interrogez le résultat jusqu'au token. Pour passer de Cloudflare Turnstile à reCAPTCHA v2 ou v3, changez le type de tâche et gardez la même boucle.
Observabilité et journalisation
Quel que soit le langage choisi, instrumentez les appels CAPTCHA pour obtenir des métriques exploitables : durée totale d'obtention du token, code retour HTTP, identifiant de tâche et taille de la file d'attente interne. Ces signaux alimentent vos tableaux de bord de QA et distinguent un ralentissement du solveur d'un ralentissement de votre réseau.
Séparez les journaux par environnement et corrélez les identifiants à votre traçage distribué (par exemple OpenTelemetry) : vous rejouerez un scénario complet à partir d'un identifiant unique. Côté conformité, minimisez les données personnelles dans les logs et vérifiez vos obligations RGPD avant de conserver des payloads bruts.
Tests et intégration continue
Ajoutez des tests d'intégration sur vos endpoints critiques et publiez des métriques par environnement : latence, taux de réussite et consommation. Vous fixez ainsi vos propres seuils d'alerte (par exemple un plancher de 95 % de réussite par type de CAPTCHA). Rendez ces tests rejouables en intégration continue : un échec bloque la fusion avant la production, garde-fou contre les régressions silencieuses d'une mise à jour de l'éditeur ou d'une dépendance.
Liste de contrôle avant la mise en production
- Périmètre limité à vos propres applications ou à des sources autorisées.
- Clé CaptchaAI dans un secret CI ou un coffre, jamais dans le code source.
- Clés séparées entre préproduction et production.
- Durées d'appel et codes retour tracés à chaque exécution.
- Retry idempotent avec backoff exponentiel borné pour les erreurs transitoires.
- Tests rejouables depuis votre intégration continue.
Dépannage
Les incidents ci-dessous couvrent la majorité des tickets pour ce type d'intégration.
| Symptôme | Cause probable | Correctif |
|---|---|---|
ERROR_WRONG_USER_KEY |
Clé copiée avec un espace parasite ou mauvais compte. | Recopiez la clé depuis le tableau de bord et stockez-la comme secret CI. |
ERROR_ZERO_BALANCE |
Solde inférieur au minimum par tâche. | Rechargez le solde et ajoutez une alerte de solde bas sur votre tableau de bord. |
| Paramètres invalides | Sitekey, URL de page ou type de tâche manquant ou mal formé. | Revalidez les entrées face au HTML réel de la page avant de soumettre. |
| Token refusé après résolution | Token appliqué dans une session différente de celle qui a déclenché le défi. | Gardez la résolution et l'envoi dans le même contexte de navigateur ou la même session HTTP. |
| Latence anormale | File d'attente saturée ou worker sous-dimensionné. | Mesurez la taille de la file et augmentez les threads du plan si nécessaire. |
FAQ
Comment exposer CaptchaAI comme outil MCP dans Cursor ou Windsurf ?
Encapsulez l'appel HTTPS à CaptchaAI dans un petit outil MCP sans état : il reçoit les paramètres du défi (sitekey, URL de page, type de tâche), obtient un token et le renvoie à l'agent, qui l'invoque comme n'importe quelle autre capacité sans manipuler votre clé API.
Où stocker la clé API et faut-il séparer les environnements ?
La clé se stocke dans un coffre ou un secret CI, montée en variable d'environnement au runtime. Séparez toujours préproduction et production : un test bruyant ne doit jamais consommer le solde de production, et la rotation reste triviale en cas de fuite.
CaptchaAI prend-il en charge hCaptcha via cet outil ?
Non — hCaptcha et FunCaptcha (Arkose Labs) ne sont pas pris en charge. L'outil couvre reCAPTCHA v2 et v3, Cloudflare Turnstile et Challenge, GeeTest v3, ainsi que les CAPTCHA image/OCR et en grille ; CaptchaFox, Friendly Captcha et Lemin sont disponibles en bêta.
Comment garder une latence et un coût prévisibles à l'échelle ?
Suivez la latence médiane et le taux de réussite par type de CAPTCHA, plafonnez les retrys à trois tentatives et rapprochez le worker des utilisateurs. Comme la facturation porte sur les threads et non sur le solve, votre coût reste stable tant que vous évitez les boucles de nouvelles tentatives dues à des paramètres erronés.
Guides connexes
- Le démarrage rapide CaptchaAI
- Faire de la QA CAPTCHA en 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
Améliorez la qualité de vos workflows CAPTCHA avec une approche méthodique et reproductible. – Obtenez votre clé CaptchaAI.
