Dépannage

Comment diagnostiquer un problème

Si un composant ne s’affiche pas, si des prompts manquent lors de la découverte ou si l’authentification tourne en boucle, commencez par déterminer d’où vient le problème : du serveur, du composant ou du client ChatGPT. Les vérifications ci-dessous vous aideront à résoudre les problèmes les plus courants.

Les vérifications relatives au serveur, aux outils et à la découverte s’appliquent aux plugins dans ChatGPT et Codex. Celles qui concernent l’interface utilisateur, l’état des widgets et l’authentification du client décrivent le fonctionnement de ChatGPT.

Problèmes côté serveur

• Aucun outil dans la liste : vérifiez que votre serveur est en cours d’exécution et que vous vous connectez au point de terminaison /mcp. Si vous avez changé de port, mettez à jour l’URL du serveur MCP et redémarrez MCP Inspector.
• Seul le contenu structuré s’affiche, sans le composant : vérifiez que, dans le descripteur de l’outil, _meta.ui.resourceUri pointe vers une ressource HTML enregistrée avec mimeType: "text/html;profile=mcp-app" (ChatGPT accepte aussi _meta["openai/outputTemplate"] comme alias de compatibilité facultatif). Vérifiez que la ressource se charge sans erreur CSP.
• Erreurs de schéma : vérifiez que vos modèles Python ou TypeScript correspondent au schéma déclaré dans outputSchema. Régénérez les types après toute modification.
• Réponses lentes : les composants semblent moins réactifs lorsque les appels d’outils prennent plus de quelques centaines de millisecondes. Analysez les performances des appels au serveur et mettez les résultats en cache lorsque c’est possible.

Problèmes liés aux widgets

• Le widget ne se charge pas : ouvrez la console du navigateur (ou les journaux de MCP Inspector) et recherchez les violations de la CSP ou les bundles manquants. Vérifiez que le HTML contient votre JavaScript compilé et que le bundle inclut toutes les dépendances.
• Les déplacements par glisser-déposer ou les modifications ne sont pas conservés : si vous utilisez ChatGPT pour conserver l’état du widget, appelez window.openai.setWidgetState après chaque mise à jour et restaurez l’état à partir de window.openai.widgetState au montage du composant.
• Problèmes de mise en page sur mobile : si votre widget utilise les indications de mise en page fournies par ChatGPT, examinez window.openai.displayMode et window.openai.maxHeight pour adapter l’affichage. Évitez les hauteurs fixes et les actions accessibles uniquement au survol.

Problèmes de découverte et de points d’entrée

• L’outil n’est jamais appelé : revoyez ses métadonnées. Reformulez les descriptions sur le modèle « Utilisez cet outil lorsque… », mettez à jour les prompts de démarrage et relancez les tests avec votre jeu de prompts de référence.
• Le mauvais outil est sélectionné : précisez ce qui distingue les outils similaires ou indiquez dans leur description les cas où leur utilisation est interdite. Envisagez de scinder les outils qui couvrent de nombreux usages en outils plus petits, chacun dédié à un usage précis.
• Le classement dans le lanceur semble incohérent : actualisez les métadonnées du plugin dans le répertoire et vérifiez que son icône et ses descriptions correspondent aux attentes des utilisateurs.

Problèmes d’authentification

• Erreurs 401 : ajoutez un en-tête WWW-Authenticate à la réponse d’erreur pour indiquer à ChatGPT qu’il doit relancer le flux OAuth. Vérifiez à nouveau les URL des émetteurs et les valeurs d’audience déclarées.
• L’enregistrement du client échoue : si vous utilisez CIMD, vérifiez que les métadonnées de votre serveur d’autorisation incluent client_id_metadata_document_supported: true et que le serveur peut récupérer le document de métadonnées du client ChatGPT. Si vous utilisez private_key_jwt, vérifiez que votre serveur d’autorisation peut récupérer le jeu de clés publiques JWKS de ChatGPT et vérifier l’assertion signée du client. Si vous utilisez DCR, vérifiez que votre serveur d’autorisation expose registration_endpoint et qu’au moins une connexion permettant de s’authentifier est activée pour chaque nouveau client.
• Une connexion existante à un serveur MCP renvoie invalid_client : vérifiez que le client OAuth enregistré dynamiquement existe toujours et que votre serveur d’autorisation accepte le secret du client, s’il en possède un. ChatGPT réutilise ces identifiants : restaurez-les plutôt que de créer un nouveau client. Si le jeton d’accès a expiré, la marche à suivre est différente.

Problèmes de déploiement

• Le délai de connexion au tunnel ngrok est dépassé : redémarrez le tunnel et vérifiez que votre serveur local est en cours d’exécution avant de partager l’URL. En production, choisissez un hébergeur fiable qui vérifie l’état du service.
• La diffusion en continu est interrompue derrière un proxy : vérifiez que votre répartiteur de charge ou votre CDN laisse passer les événements envoyés par le serveur ou les réponses HTTP en continu sans les mettre en mémoire tampon.

Quand contacter votre interlocuteur chez OpenAI

Si le problème persiste après ces vérifications :

1. Rassemblez les journaux du serveur, les messages de la console du composant, la transcription des appels d’outils de ChatGPT et des captures d’écran.
2. Notez le prompt que vous avez envoyé ainsi que les éventuels messages de confirmation.
3. Transmettez ces éléments à votre interlocuteur partenaire chez OpenAI pour qu’il puisse reproduire le problème en interne.

Un compte rendu de dépannage clair et concis réduit le délai de résolution et vous aide à maintenir la fiabilité de votre serveur MCP pour les utilisateurs.