Depuis que le MCP Adapter s’est répandu sur des projets WordPress clients, notre équipe support reçoit régulièrement les mêmes trois familles d’incidents : une authentification refusée, un schéma d’outil rejeté par le client, ou un outil qui existe côté serveur mais n’apparaît jamais côté client. Cet article ne reprend pas l’installation du MCP Adapter, déjà traitée ailleurs : il se concentre uniquement sur le diagnostic et la résolution de ces trois familles de pannes, dans l’ordre où nous les rencontrons le plus souvent.
Symptôme 1 : erreur 401 à la connexion
Le client MCP affiche une erreur d’authentification dès la tentative de connexion au serveur exposé par WordPress, alors que les identifiants semblent corrects. Diagnostic : dans la grande majorité des cas que nous avons traités, le jeton d’application utilisé existe bien et fonctionne pour des appels REST classiques, mais ne dispose pas du périmètre attendu par la configuration MCP, qui vérifie souvent une capacité précise en plus de l’authentification de base. Un jeton valide pour lire des articles via l’API REST peut être refusé si le point de terminaison MCP exige explicitement la capacité manage_options pour l’ensemble de la connexion.
Correctif : vérifier dans les réglages du MCP Adapter quelle capacité est associée au périmètre demandé, puis s’assurer que l’utilisateur propriétaire du jeton la possède réellement, via user_can testé directement dans une console WP-CLI avec wp eval. Prévention : documenter dans le projet la capacité exacte requise par chaque intégration MCP, pour éviter de la redécouvrir par tâtonnement au prochain incident.
Symptôme 2 : schéma refusé par le client
Le serveur démarre normalement, la connexion s’établit, mais le client MCP rejette un ou plusieurs outils au moment de charger leur définition, parfois sans message d’erreur explicite côté interface. Diagnostic : ce cas provient presque toujours d’un type de paramètre non supporté ou mal formé dans le schéma JSON généré automatiquement à partir des routes REST sous-jacentes, en particulier sur des paramètres à énumération complexe ou des types union que certains clients interprètent différemment.
Corriger un schéma trop permissif ou mal typé
Correctif : simplifier le schéma exposé pour l’outil concerné, en explicitant le type attendu plutôt que de laisser une inférence automatique trop large produire un schéma ambigu. Sur un cas rencontré, un paramètre de date accepté à la fois en format ISO et en timestamp Unix produisait un schéma que le client refusait de charger ; le fixer à un seul format a résolu l’incident immédiatement.
// Avant : type ambigu généré automatiquement
"date_publication": { "type": ["string", "integer"] }
// Après : type unique explicite dans la déclaration de l'outil
"date_publication": { "type": "string", "format": "date-time" }
Prévention : tester chaque nouvel outil MCP ajouté avec au moins deux clients différents avant mise en production, certains schémas passant chez l’un et échouant silencieusement chez l’autre.
Symptôme 3 : un outil invisible côté client
L’outil existe bien dans la configuration serveur, aucune erreur ne remonte dans les journaux, mais il n’apparaît simplement pas dans la liste des outils disponibles côté client connecté. Diagnostic : ce comportement signale presque toujours un échec silencieux de la vérification de permission au moment où le client demande la liste des outils disponibles, WordPress retirant discrètement de la liste tout outil que l’utilisateur authentifié n’est pas autorisé à voir, sans lever d’erreur explicite pour ne pas révéler l’existence de fonctionnalités restreintes.
Vérifier la permission au bon niveau
Correctif : contrôler séparément la permission de listage de l’outil et la permission d’exécution, ces deux vérifications utilisant parfois des capacités différentes dans une configuration mal alignée. Activer temporairement un niveau de journalisation détaillé sur le MCP Adapter permet généralement de voir la vérification de permission échouer silencieusement dans les journaux serveur, même sans remontée visible côté client.
- Vérifier en priorité la capacité associée au jeton avant de suspecter les identifiants
- Fixer un type unique et explicite pour chaque paramètre de schéma exposé
- Tester tout nouvel outil avec plusieurs clients MCP différents avant mise en production
- Distinguer la permission de listage de la permission d’exécution d’un outil
Une erreur silencieuse reste la pire à diagnostiquer. Activer la journalisation détaillée avant de chercher ailleurs fait gagner un temps précieux.
En résumé
Ces trois familles d’incidents couvrent la grande majorité des cas que nous corrigeons sur des intégrations MCP Adapter en production. Le réflexe qui fait gagner le plus de temps reste le même dans les trois cas : activer la journalisation détaillée avant de formuler des hypothèses, plutôt que de deviner la cause à partir du seul symptôme visible côté client.
