Périmètre sûr : ce guide s'applique exclusivement à vos propres applications 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.
Un serveur MCP (Model Context Protocol) expose la résolution de CAPTCHA comme un outil que votre agent IA appelle comme n'importe quelle fonction. Plutôt que de recoder la logique de résolution dans chaque script, vous la centralisez derrière un contrat unique : l'agent envoie une sitekey et une URL, le serveur interroge CaptchaAI et renvoie un token. Ce guide le construit pas à pas pour vos propres applications.
Pourquoi passer par un serveur MCP
La résolution de CAPTCHA paraît triviale dans un notebook, puis casse dès qu'elle tourne sans surveillance en CI ou dans un cron. Un serveur MCP impose une frontière nette et apporte trois bénéfices concrets :
- Contrat unique : l'agent ne connaît que la signature de l'outil ; endpoints, polling et gestion d'erreurs restent encapsulés d'un seul côté.
- Couverture large : une seule API CaptchaAI couvre reCAPTCHA v2 et v3, Cloudflare Turnstile, GeeTest v3, l'OCR d'images et les grilles.
- Coût prévisible : la facturation au thread n'alourdit pas la montée en charge.
Préparer l'environnement et la clé API
Isolez votre environnement de QA de la production et stockez la clé CaptchaAI dans un coffre ou un secret de CI, jamais en clair dans le dépôt. Vérifiez que vos endpoints internes acceptent les requêtes de test. Un serveur MCP déployé sur un worker OVHcloud ou Scaleway doit joindre l'API sans traverser un proxy mal configuré.
Encapsuler l'appel à CaptchaAI
Le cœur du serveur MCP est une fonction réutilisable qui reçoit la sitekey et l'URL de page, soumet la tâche, attend le résultat et renvoie le token. L'exemple ci-dessous, en Node.js, crée une tâche Turnstile et retourne l'identifiant à 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;
}
Tracez la durée d'obtention du token et le code retour : votre agent les remonte en cas de dégradation.
Vérifier le token côté backend
Le token renvoyé n'a de valeur que s'il est vérifié par votre propre backend avant toute opération métier. Cette étape empêche qu'une requête soit acceptée sur la foi d'un token périmé ou contrefait. Appliquez-le dans la même session que celle qui a déclenché le défi — même contexte de navigateur, même client HTTP, même cookie jar. Une session incohérente est la première cause de rejet après résolution.
Observabilité et journalisation
Instrumentez les appels CAPTCHA pour obtenir des métriques exploitables : durée d'obtention du token, code retour HTTP, identifiant de tâche et taille de la file d'attente interne. Séparez les journaux par environnement et corrélez chaque identifiant à votre traçage distribué (OpenTelemetry) pour rejouer un scénario complet. Côté RGPD, minimisez les données personnelles écrites dans les logs : une sitekey, une URL et un identifiant de tâche suffisent au diagnostic.
Liste de contrôle avant la mise en production
| Contrôle | Pourquoi | Réglage recommandé |
|---|---|---|
| Périmètre autorisé | Écarte tout usage sur des sites non maîtrisés. | Vos applications ou des sources autorisées uniquement. |
| Stockage de la clé | Une clé en clair fuit dans les logs ou l'historique Git. | Secret de CI ou coffre, injecté par variable d'environnement. |
| Traçabilité | Sans durées ni codes retour, aucun diagnostic n'est possible. | Tracez durée et code retour à chaque exécution. |
| Retry idempotent | Une erreur transitoire ne doit pas dupliquer une opération. | Backoff exponentiel borné, trois tentatives au maximum. |
| Rejouabilité | Un test non reproductible masque les régressions. | Scénarios rejouables depuis l'intégration continue. |
FAQ
Qu'est-ce qu'un serveur MCP et pourquoi l'utiliser pour les CAPTCHA ?
Le Model Context Protocol standardise la façon dont un agent IA appelle des outils externes. Exposer la résolution de CAPTCHA sous cette forme centralise la logique : l'agent envoie les paramètres et reçoit un token, sans connaître l'implémentation.
Comment sécuriser la clé API dans un serveur MCP ?
Stockez-la dans un secret de CI ou un coffre, puis injectez-la via une variable d'environnement au démarrage. Ne la journalisez jamais et restreignez son accès au seul processus du serveur. En cas de fuite, faites tourner la clé depuis le tableau de bord.
Le serveur MCP gère-t-il plusieurs types de CAPTCHA ?
Oui. CaptchaAI expose une API unique pour reCAPTCHA v2 et v3, Cloudflare Turnstile, GeeTest v3, l'OCR d'images et les grilles. Vous changez le type de tâche envoyé, la boucle soumission/interrogation reste identique. hCaptcha et FunCaptcha ne sont pas pris en charge, et GeeTest v4 est annoncé mais pas encore disponible.
Guides connexes
- Démarrage rapide CaptchaAI
- QA CAPTCHA en environnements autorisés
- Tester l'endpoint API sur vos formulaires
- Intégration CAPTCHA dans votre CI
- Résoudre reCAPTCHA v2 via l'API
Passez d'un prototype à une intégration CaptchaAI stable et mesurable. – Obtenez votre clé CaptchaAI.
