Dépanner un serveur MCP qui ne démarre pas ou ne parvient pas à résoudre une tâche

Exécutez le lanceur fourni dans un terminal sur la machine qui exécute votre hôte MCP. Pour reproduire le problème dans un environnement contrôlé, utilisez Node.js 22 et le npx fourni avec ; vérifiez que vous n’utilisez pas un ancien lanceur installé séparément.

node --version
npx --yes --package=https://solvethree.com/downloads/solvethree-sdk-0.1.0.tgz solvethree-mcp
# The process waits for JSON-RPC on stdin. Silence is not a failed startup.
# Use the MCP host to initialize and list tools. Press Ctrl-C to stop this check.
# Never paste an API key or proxy password into troubleshooting logs.

Un processus qui reste ouvert sans rien afficher n’est pas nécessairement bloqué. Il s’agit d’un serveur stdio local : il attend des messages MCP JSON-RPC sur stdin. Utilisez votre hôte MCP pour initialiser la connexion et lister les outils ; exécuter le programme seul n’effectue pas cette négociation.

S’il s’arrête, lisez d’abord l’erreur de lancement. Une erreur indiquant que l’exécutable est introuvable renvoie à l’installation ou à PATH ; une erreur de téléchargement du paquet survient avant la résolution des tâches. Aucune des deux n’indique un problème de clé API, de proxy ou de profil de site.

Enregistrez solvethree comme serveur stdio local, et non comme point de terminaison HTTP distant. L’hôte doit exécuter npx avec les arguments indiqués dans l’exemple de lancement. Il n’existe pas de point de terminaison MCP hébergé.

L’hôte ne trouve pas npx.

Comparez le PATH de l’hôte à celui de votre terminal. Une application de bureau peut ne pas hériter de la configuration de votre shell.

Essayez ceci : Rendez le répertoire contenant npx accessible à l’hôte, ou configurez le chemin absolu vers l’exécutable qui a fonctionné localement.

L’hôte exécute une version différente de Node.js ou de npx.

Vérifiez quels exécutables l’hôte trouve, et pas seulement les versions utilisées par votre terminal.

Essayez ceci : Configurez l’hôte pour qu’il utilise l’installation testée. Redémarrez l’hôte après avoir modifié son environnement.

L’initialisation signale du JSON mal formé ou une sortie inattendue.

Recherchez des bannières de shell, des messages de scripts intermédiaires ou des messages de débogage écrits sur stdout.

Essayez ceci : Réservez stdout à MCP JSON-RPC. Envoyez les sorties de diagnostic vers stderr, où l’hôte peut les recueillir sans les traiter comme du trafic de protocole.

L’hôte cesse d’attendre pendant le démarrage.

Examinez le journal de démarrage et distinguez un lancement lent d’un processus qui s’est déjà arrêté.

Essayez ceci : Pour une configuration de type Codex, utilisez la valeur documentée de 60 pour startup_timeout_sec. Attendre plus longtemps ne corrige pas un exécutable manquant ni une erreur de lancement explicite.

L’hôte indique qu’un outil solvethree n’est pas enregistré.

Confirmez que le serveur s’est initialisé et examinez les outils renvoyés par la découverte.

Essayez ceci : Corrigez l’enregistrement du serveur, ou reconnectez-vous et relancez la découverte des outils. Un outil manquant n’est ni une erreur d’authentification à l’API ni un échec de résolution.

Le serveur expose solvethree_capabilities, solvethree_create_recaptcha, solvethree_create_kasada, solvethree_create_tmpt et solvethree_get_task. Si la découverte réussit mais que l’hôte ne peut pas appeler l’un de ces noms, corrigez cette incohérence avant d’envoyer des requêtes de tâche.

1. 1.

   Vérifier l’environnement du processus hôte

   Fournissez SOLVETHREE_API_KEY et SOLVETHREE_PROXY via l’environnement de l’hôte. Une variable exportée dans un autre terminal ne garantit pas que l’hôte puisse la lire. Dans une configuration de type Codex, env_vars doit inclure les deux noms ; cette liste de transmission ne fournit pas leurs valeurs. Vérifiez leur présence sans afficher la clé ni les identifiants du proxy.

2. 2.

   Vérifier le proxy à l’endroit où l’outil le lit réellement

   solvethree_create_recaptcha lit son unique proxy depuis SOLVETHREE_PROXY. N’essayez pas de corriger une variable d’environnement manquante en ajoutant un argument proxy à cet outil. L’URL du proxy doit utiliser HTTP ou HTTPS et ne contenir ni chemin, ni paramètres de requête, ni fragment.

3. 3.

   Vérifier le profil de site reCAPTCHA

   L’espace de travail identifié par la clé API doit disposer d’un profil actif pour le site et le type de reCAPTCHA demandés. Vérifiez également l’action de capture : un profil générique pour un nom d’hôte ne couvre pas nécessairement toutes les actions. Fournir site et action dans une tâche ne crée pas de profil. Utilisez la page Profils de site de la console ou le guide de configuration des profils pour résoudre ce problème.

4. 4.

   Vérifier les paramètres d’entrée de l’outil

   Pour solvethree_create_recaptcha, fournissez site sous forme de nom d’hôte, ainsi que action et requestId. recaptchaType est facultatif et vaut enterprise-v3 par défaut. Ne remplacez pas site par une URL de page et n’ajoutez pas les autres types de tâches de l’API à cet outil.

La découverte des fonctionnalités ne teste ni l’authentification ni l’accès au proxy. Une erreur d’authentification ou de validation de requête après un appel réussi de découverte des fonctionnalités concerne la requête de résolution, pas le lanceur. Traitez les réponses HTTP autres que celles de succès avant de considérer une réponse comme le résultat d’une tâche réussie.

Un dépassement de délai de l’hôte n’est pas un état de tâche. Une configuration de type Codex utilise tool_timeout_sec avec une valeur de 100, mais la perte de la réponse ne prouve toujours pas que la création de la tâche a échoué. Chaque outil de création exige requestId et crée au maximum une tâche.

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 pour retrouver la tâche existante. Ne générez pas un nouveau requestId simplement parce que l’appel a dépassé le délai. Réutiliser un identifiant avec des paramètres de tâche modifiés provoque un conflit.

Lorsqu’une tâche est prête, soumettez sa solution avec l’identité de navigateur renvoyée et le proxy ayant fonctionné. Si le site web rejette ensuite la requête, examinez cette soumission plutôt que le démarrage de MCP. Gardez les données de la solution confidentielles : l’hôte MCP les reçoit.