Dépannage MCP

Avant de réessayer, diagnostiquez les problèmes de découverte des outils, d’authentification, d’accès à l’organisation et d’arguments, ainsi que les résultats incertains.

Déterminez la prochaine vérification à partir du symptôme : si un outil manque, examinez la connexion ; si un appel est rejeté, vérifiez l’erreur d’argument ou d’autorisation. Conservez le nom de l’outil, les données d’entrée non confidentielles, la réponse et la ressource ou la révision source concernée. Ces éléments permettent de reprendre le travail prévu sans répéter une opération d’écriture dont le résultat est inconnu.

Les outils attendus sont absents #

Comparez le point de terminaison configuré à l’inventaire renvoyé par le client. /mcp et /main exposent les mêmes outils accessibles après authentification ; /account redirige vers /main après l’authentification.

Recherchez members_listMemberships et engines_list, puis suivez les exemples de première lecture. Consultez la réponse actuelle de tools/list pour obtenir les noms et les schémas exacts. L’existence d’un point de terminaison API ne signifie pas que MCP l’expose.

Si seuls certains outils sont masqués, vérifiez la liste d’autorisation et les approbations du client, puis activez uniquement les outils nécessaires à la tâche. Si un outil attendu est absent, conservez les informations sur le serveur et sa version, ainsi que les résultats de découverte non confidentiels, pour les joindre à un signalement.

GET renvoie 405 #

Configurez HTTP en streaming sur /mcp. Après l’authentification, une requête GET sur /mcp ou /main renvoie 405 avec Allow: POST ; le client envoie les messages MCP avec POST. Si le jeton est absent ou non valide, le serveur renvoie 401 avant l’acheminement. Une requête authentifiée vers /account renvoie, quant à elle, 308 vers /main. Ces réponses GET ne permettent pas de vérifier le bon fonctionnement d’une connexion MCP POST valide. Après avoir sélectionné le bon transport, examinez l’erreur de connexion du client.

L’authentification ou l’organisation est incorrecte #

Pour 401, vérifiez que la connexion a bien effectué l’authentification OAuth avec le compte Lingo.dev souhaité. Le serveur hébergé exige un jeton Bearer utilisateur valide ; une clé API personnelle ou de service n’est acceptée ni dans x-api-key ni comme valeur Bearer. Laissez le client renouveler son autorisation ou rétablissez la connexion depuis sa gestion des comptes. N’incluez aucun jeton dans les diagnostics.

Appelez members_listMemberships, choisissez l’organisation souhaitée dans data, puis transmettez son ID dans le champ d’organisation de l’outil suivant. Pour engines_list, il s’agit du champ orgId. Choisir une autre organisation dans la même liste ne nécessite pas de nouvelle autorisation OAuth. Rétablissez la connexion si le compte connecté n’est pas le bon ; un simple redémarrage peut réutiliser la session enregistrée.

Si l’appartenance figure dans ssoRequired, connectez-vous à Lingo.dev via le fournisseur d’identité de cette organisation, puis rétablissez la connexion. Si data et ssoRequired sont tous deux vides, terminez la configuration de l’organisation sur https://lingo.dev/orgs/start, puis consultez à nouveau les appartenances. Une organisation indisponible peut être absente, ne pas figurer parmi les organisations dont l’utilisateur est membre ou exiger le SSO ; n’interprétez pas systématiquement ces réponses comme le signe d’un identifiant expiré.

Si un outil refuse une opération faute d’autorisation ou de droits d’accès, examinez les exigences de l’opération au lieu de répéter l’authentification. L’accès à l’organisation et l’autorisation d’effectuer une écriture donnée font l’objet de vérifications distinctes. Expliquez quels droits manquent, sans choisir en silence un rôle ou un identifiant doté de droits plus étendus.

Un outil indique que la configuration de l’organisation n’est pas terminée #

L’organisation a été créée récemment et la personne qui l’a créée n’a pas terminé sa configuration dans l’application web : intégrations, membres de l’équipe et premier moteur. Les outils au niveau de l’organisation peuvent rester bloqués tant que la configuration n’est pas terminée ; réessayer ou renouveler l’autorisation ne permet pas d’accomplir ces étapes. members_listMemberships reste disponible. Ouvrez le lien du message, https://lingo.dev/orgs/<orgId>, avec le compte de la personne qui a créé l’organisation, terminez les étapes indiquées, puis répétez l’appel. Consultez Terminer la configuration d’une nouvelle organisation.

L’outil rejette les arguments #

Comparez les données d’entrée au schéma exact renvoyé par la connexion. Les arguments actuels des outils sont des champs à plat ; les valeurs imbriquées restent aux emplacements prévus par le schéma. N’ajoutez pas de conteneurs body, params ou query non prévus. Renseignez explicitement le champ d’organisation lorsqu’il est requis ; il n’est pas injecté à partir du jeton Bearer. Le champ facultatif intent décrit la tâche. Consultez Fonctionnalités pour connaître les opérations de compte prises en charge.

Vérifiez à quoi correspond chaque ID. members_remove.id est l’ID d’appartenance fourni par members_list ; members_setRole.userId identifie l’utilisateur associé à cette appartenance. Un ID de moteur de localisation ne peut pas remplacer un ID de journal de requêtes. Copiez à l’identique les curseurs opaques ou les paires horodatage/ID en conservant toute leur précision, au lieu de les reconstituer à partir des dates affichées.

Respectez les distinctions du schéma entre valeurs omises et valeurs nulles, nombres et chaînes, tableaux et valeurs uniques. Vérifiez le schéma de l’outil connecté avant de contourner une erreur d’argument.

Le résultat d’une écriture sur le compte ou d’une tâche est incertain #

Consultez la ressource concernée ou l’état de la tâche avant de réessayer. Une erreur réseau peut survenir après que le serveur a accepté la création d’une clé, une invitation, une décision de relecture, une suggestion ou une tâche. Vérifiez si la modification prévue existe déjà au lieu de la soumettre à nouveau automatiquement.

Pour une tâche de provisionnement que vous avez soumise, consultez provisioningJobs_get avec l’ID de tâche enregistré avant de décider de réessayer. Pour les autres opérations, examinez la ressource enregistrée et les conditions d’achèvement définies par l’outil connecté. Pour les workflows de traduction, consultez la référence CLI ou API.

La documentation ou les éléments de preuve manquent #

Effectuez une recherche avec localization_search, puis transmettez le path d’un résultat à docs_fetch pour lire la page complète. Si le chemin ne fonctionne pas, relancez une recherche sur la tâche et utilisez un résultat à jour. La base de connaissances utilise un chemin de stockage distinct de celui du site web reposant sur des fichiers ; une page du site peut donc être absente ou obsolète dans cet index. Consultez la référence à jour sur le site web avant de conclure que la fonctionnalité est indisponible.

Lorsque vous signalez une lacune MCP non résolue, indiquez la tâche tentée, le nom exact de l’outil, la version du serveur et la réponse, sans données confidentielles. L’accusé de réception d’un signalement ne garantit aucune date de correction.

Pour une question de qualité, déterminez ce qui manque : des éléments de preuve issus de la source, une évaluation terminée, un critère applicable ou une réponse claire. Chacun de ces cas appelle une suite différente. Mesurer explique comment présenter les éléments de preuve disponibles sans considérer les cas sans réponse comme des réussites.