Dépannage

Comment diagnostiquer les problèmes

Lorsqu’un problème survient (composants qui ne s’affichent pas, outils non détectés pour certains prompts, boucles d’authentification), commencez par identifier la couche responsable : serveur, composant ou client ChatGPT. La liste de vérification ci-dessous présente les problèmes les plus courants et leurs solutions.

Les vérifications du serveur, des outils et de leur découverte s’appliquent aux plugins dans ChatGPT et Codex. Les vérifications de l’interface, de l’état des widgets et de l’authentification du client présentées sur cette page décrivent le comportement de ChatGPT.

Problèmes côté serveur

• Aucun outil répertorié : 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.
• Du contenu structuré, mais aucun composant : Vérifiez que le descripteur de l’outil fait pointer _meta.ui.resourceUri vers une ressource HTML enregistrée avec mimeType: "text/html;profile=mcp-app" (ChatGPT accepte _meta["openai/outputTemplate"] comme alias de compatibilité facultatif) et que la ressource se charge sans erreur CSP.
• Erreurs de non-conformité au 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 paraissent peu 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 de widgets

• Le widget ne se charge pas : Ouvrez la console du navigateur (ou les journaux de MCP Inspector) pour rechercher des violations de la CSP ou des bundles manquants. Vérifiez que le HTML contient votre JavaScript compilé et que le bundle contient toutes les dépendances.
• Les glisser-déposer ou les modifications ne sont pas conservés : Si vous utilisez la persistance de l’état des widgets de ChatGPT, appelez window.openai.setWidgetState après chaque mise à jour et restaurez l’état à partir de window.openai.widgetState lors du montage.
• Problèmes de mise en page sur mobile : Si vous utilisez les informations de mise en page fournies par ChatGPT, inspectez window.openai.displayMode et window.openai.maxHeight pour ajuster la mise en page. É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 vos métadonnées. Reformulez les descriptions en commençant par « 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é : Ajoutez des précisions pour distinguer les outils similaires ou indiquez les cas d’utilisation interdits dans la description. Envisagez de scinder les outils aux fonctions étendues en outils plus petits et spécialisés.
• Le classement dans le lanceur semble inadapté : Actualisez vos métadonnées dans l’annuaire et vérifiez que l’icône et les descriptions du plugin correspondent aux attentes des utilisateurs.

Problèmes d’authentification

• Erreurs 401 : Incluez un en-tête WWW-Authenticate dans la réponse d’erreur pour indiquer à ChatGPT qu’il doit relancer le flux OAuth. Vérifiez soigneusement les URL de l’émetteur et les revendications d’audience.
• 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 ce serveur peut récupérer le document de métadonnées client de ChatGPT. Pour private_key_jwt, vérifiez que votre serveur d’autorisation peut récupérer le JWKS public de ChatGPT et vérifier l’assertion client signée. Si vous utilisez DCR, vérifiez que votre serveur d’autorisation expose registration_endpoint et qu’au moins une connexion d’authentification est activée pour les clients nouvellement créés.
• 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 son secret client, s’il en possède un. ChatGPT réutilise ces identifiants : restaurez-les plutôt que de créer un nouveau client. Un token d’accès expiré nécessite une autre correction.

Problèmes de déploiement

• Le délai d’attente du tunnel ngrok expire : Redémarrez le tunnel et vérifiez que votre serveur local est en cours d’exécution avant de partager l’URL. En production, utilisez un hébergeur stable proposant des contrôles de bon fonctionnement.
• La diffusion en continu s’interrompt derrière des proxys : Vérifiez que votre répartiteur de charge ou votre CDN autorise les événements envoyés par le serveur ou les réponses HTTP en continu sans mise en mémoire tampon.

Quand demander de l’aide

Si vous avez vérifié les points ci-dessus et que le problème persiste :

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

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