Ajouter la résolution de CAPTCHA à votre agent IA avec MCP

Le téléchargement officiel de @solvethree/sdk inclut l’exécutable solvethree-mcp. Les configurations ci-dessous utilisent npx pour l’exécuter à partir de l’URL du paquet fournie. Il n’y a pas d’URL de point de terminaison MCP hébergé à saisir.

• Rendez npx disponible dans l’environnement où s’exécute votre hôte MCP.
• Définissez SOLVETHREE_API_KEY sur la clé API de votre espace de travail dans l’environnement de l’hôte. Ne l’incluez ni dans le code du navigateur ni dans les prompts.
• Définissez SOLVETHREE_PROXY dans cet environnement. L’outil reCAPTCHA lit son unique proxy dans cette variable, et non dans la requête adressée à l’outil.

Pour un hôte qui accepte une configuration MCP en JSON, ajoutez cette entrée de serveur :

{
  "mcpServers": {
    "solvethree": {
      "command": "npx",
      "args": [
        "--yes",
        "--package=https://solvethree.com/downloads/solvethree-sdk-0.1.0.tgz",
        "solvethree-mcp"
      ]
    }
  }
}

Pour Codex, utilisez plutôt cette configuration TOML. Son entrée env_vars transmet les deux variables de l’environnement de l’hôte ; elle ne définit pas leurs valeurs.

[mcp_servers.solvethree]
command = "npx"
args = ["--yes", "--package=https://solvethree.com/downloads/solvethree-sdk-0.1.0.tgz", "solvethree-mcp"]
env_vars = ["SOLVETHREE_API_KEY", "SOLVETHREE_PROXY"]
startup_timeout_sec = 60
tool_timeout_sec = 100

Démarrez ou rechargez l’hôte avec ces variables d’environnement disponibles. Vérifiez qu’il expose solvethree_capabilities, solvethree_create_recaptcha, solvethree_create_kasada, solvethree_create_tmpt et solvethree_get_task.

Avant de créer une tâche reCAPTCHA, configurez le profil du site cible et assurez-vous qu’il est actif pour votre espace de travail. L’envoi d’un nom d’hôte et d’une action via MCP ne crée pas ce profil.

Utilisez solvethree_capabilities pour examiner les fonctionnalités disponibles. Pour reCAPTCHA v3 Enterprise, appelez solvethree_create_recaptcha avec cette requête :

{
  "site": "accounts.example.com",
  "action": "login",
  "requestId": "agent-login-001",
  "waitMs": 0
}

Remplacez accounts.example.com par votre site cible et login par l’action dont votre application a besoin. Choisissez un requestId pour cette tâche logique et conservez-le avec la requête. Avec waitMs défini sur zéro, récupérez le résultat séparément plutôt que d’attendre la fin de la tâche dans cet appel.

Chaque création via MCP nécessite un requestId, même si ce champ est facultatif dans l’API de tâches sous-jacente. Utilisez 1–64 lettres ASCII, chiffres, traits de soulignement ou traits d’union.

1. 1.

   Conserver l’identifiant de tâche renvoyé

   La création de la tâche n’est pas le résultat. Enregistrez l’identifiant de la tâche pour que l’agent puisse récupérer cette même tâche.

2. 2.

   Appeler solvethree_get_task

   Utilisez l’identifiant de tâche renvoyé par l’appel de création. Si l’état est pending ou solving, récupérez de nouveau la tâche plus tard. Aucun de ces états ne contient de solution utilisable.

3. 3.

   Traiter l’état terminal

   À l’état ready, transmettez la solution à votre intégration au navigateur ou à l’application. À l’état failed, examinez errorCode et error, puis cessez d’interroger cette tâche.

Pour reCAPTCHA, soumettez solution.token via votre navigateur ou une requête de votre application. Définissez ses en-têtes User-Agent et sec-ch-ua à partir des valeurs userAgent et secChUa renvoyées, et réutilisez le proxy configuré dans SOLVETHREE_PROXY. Maintenez cette session de proxy sur le même point de sortie si votre fournisseur effectue une rotation des points de sortie.

Kasada renvoie des en-têtes et Ticketmaster TMPT renvoie une valeur de cookie brute. Appliquez le résultat correspondant à la tâche demandée ; ces résultats ne sont pas interchangeables.

Le serveur MCP ne pilote pas de navigateur et ne remplit pas de formulaires. Son hôte reçoit des données de résolution privées, et votre application se charge de les soumettre. Vérifiez séparément la réponse de la cible : le statut ready signifie que solvethree a généré une solution, pas que la cible l’a acceptée.

Un dépassement du délai de connexion ne prouve pas que la création de la tâche a échoué. Si vous avez reçu un identifiant de tâche, récupérez cette tâche. Sinon, répétez la même requête de création avec le même requestId et les mêmes paramètres de tâche pour récupérer la tâche existante. Ne générez pas un nouvel identifiant simplement parce que la réponse a été perdue.

Réutiliser un identifiant de requête avec des paramètres de tâche différents provoque un conflit. Si la tâche elle-même a échoué, lisez son erreur avant de décider quoi modifier ; renvoyer aveuglément des paramètres invalides ne les corrigera pas. Pour distinguer les erreurs de requête des échecs de tâche, consultez les erreurs de l’API CAPTCHA.