Fehlerbehebung

Probleme eingrenzen

Wenn etwas schiefläuft, etwa Komponenten nicht angezeigt werden, passende Prompts nicht erkannt werden oder die Authentifizierung in einer Schleife festhängt, grenze zunächst die Ursache ein: Liegt sie beim Server, bei der Komponente oder beim ChatGPT-Client? Die folgende Checkliste beschreibt die häufigsten Probleme und ihre Lösungen.

Die Prüfungen für Server, Werkzeuge und Auffindbarkeit gelten für Plug-ins in ChatGPT und Codex. Die Prüfungen zu Benutzeroberflächen, Widget-Zustand und Client-Authentifizierung auf dieser Seite beschreiben das Verhalten von ChatGPT.

Serverseitige Probleme

• Keine Werkzeuge aufgelistet: Prüfe, ob dein Server läuft und du dich mit dem Endpunkt /mcp verbindest. Wenn du die Ports geändert hast, aktualisiere die URL des MCP-Servers und starte MCP Inspector neu.
• Nur strukturierte Inhalte, keine Komponente: Prüfe, ob der Werkzeugdeskriptor _meta.ui.resourceUri auf eine registrierte HTML-Ressource mit mimeType: "text/html;profile=mcp-app" setzt (ChatGPT akzeptiert _meta["openai/outputTemplate"] als optionalen Kompatibilitätsalias) und ob die Ressource ohne CSP-Fehler geladen wird.
• Fehler durch abweichende Schemas: Stelle sicher, dass deine Python- oder TypeScript-Modelle dem in outputSchema angegebenen Schema entsprechen. Generiere die Typen nach Änderungen neu.
• Lange Antwortzeiten: Komponenten wirken träge, wenn Werkzeugaufrufe länger als einige Hundert Millisekunden dauern. Analysiere die Laufzeiten der Serveraufrufe und speichere Ergebnisse nach Möglichkeit im Cache.

Probleme mit Widgets

• Widget wird nicht geladen: Öffne die Browserkonsole (oder die Protokolle von MCP Inspector) und suche nach CSP-Verstößen oder fehlenden Bundles. Stelle sicher, dass das HTML deinen kompilierten JavaScript-Code enthält und das Bundle alle Abhängigkeiten umfasst.
• Änderungen durch Drag-and-drop oder Bearbeitung bleiben nicht erhalten: Wenn du die Speicherung des Widget-Zustands durch ChatGPT nutzt, rufe nach jeder Aktualisierung window.openai.setWidgetState auf und stelle den Zustand beim Mounten aus window.openai.widgetState wieder her.
• Layoutprobleme auf Mobilgeräten: Wenn du die Layoutsignale von ChatGPT nutzt, prüfe window.openai.displayMode und window.openai.maxHeight, um das Layout anzupassen. Vermeide feste Höhen und Aktionen, die nur beim Darüberfahren mit der Maus verfügbar sind.

Probleme mit Auffindbarkeit und Einstiegspunkten

• Werkzeug wird nie aufgerufen: Überprüfe deine Metadaten. Formuliere Beschreibungen nach dem Muster „Verwende dies, wenn …“, aktualisiere die Einstiegs-Prompts und teste erneut mit deinem Referenzsatz an Prompts.
• Falsches Werkzeug ausgewählt: Ergänze bei ähnlichen Werkzeugen klarstellende Details oder gib in der Beschreibung an, in welchen Szenarien sie nicht verwendet werden dürfen. Erwäge, umfangreiche Werkzeuge in kleinere, spezialisierte Werkzeuge aufzuteilen.
• Reihenfolge im Launcher wirkt unpassend: Aktualisiere deine Metadaten im Verzeichnis und stelle sicher, dass das Plug-in-Symbol und die Beschreibungen den Erwartungen der Nutzenden entsprechen.

Probleme mit der Authentifizierung

• 401-Fehler: Füge der Fehlerantwort einen WWW-Authenticate-Header hinzu, damit ChatGPT erkennt, dass der OAuth-Ablauf erneut gestartet werden muss. Prüfe die Issuer-URLs und Audience-Claims sorgfältig.
• Client-Registrierung schlägt fehl: Wenn du CIMD verwendest, prüfe, ob die Metadaten deines Autorisierungsservers client_id_metadata_document_supported: true enthalten und der Server das Client-Metadatendokument von ChatGPT abrufen kann. Prüfe für private_key_jwt, ob dein Autorisierungsserver die öffentlichen JWKS von ChatGPT abrufen und die signierte Client-Assertion prüfen kann. Wenn du DCR verwendest, prüfe, ob dein Autorisierungsserver registration_endpoint bereitstellt und für neu erstellte Clients mindestens eine Anmeldeverbindung aktiviert ist.
• Eine bestehende Verbindung zu einem MCP-Server gibt invalid_client zurück: Prüfe, ob der dynamisch registrierte OAuth-Client noch existiert und dein Autorisierungsserver sein Client-Secret akzeptiert, sofern eines vorhanden ist. ChatGPT verwendet diese Anmeldedaten erneut. Stelle sie daher wieder her, statt einen neuen Client zu erstellen. Ein abgelaufenes Zugriffstoken erfordert eine andere Lösung.

Probleme bei der Bereitstellung

• Zeitüberschreitung beim ngrok-Tunnel: Starte den Tunnel neu und prüfe, ob dein lokaler Server läuft, bevor du die URL teilst. Verwende für den Produktivbetrieb einen zuverlässigen Hosting-Anbieter mit Zustandsprüfungen.
• Streaming funktioniert hinter Proxys nicht: Stelle sicher, dass dein Load Balancer oder CDN Server-Sent Events oder gestreamte HTTP-Antworten ohne Pufferung zulässt.

Wann du das Problem eskalieren solltest

Wenn du die oben genannten Punkte geprüft hast und das Problem weiterhin besteht:

1. Sammle Protokolle (Server, Komponentenkonsole, Protokoll der Werkzeugaufrufe in ChatGPT) und Screenshots.
2. Notiere den eingegebenen Prompt und alle Bestätigungsmeldungen.
3. Teile die Details mit deiner Kontaktperson für die Partnerschaft bei OpenAI, damit das Problem intern reproduziert werden kann.

Ein präzises Fehlerbehebungsprotokoll verkürzt die Bearbeitungszeit und trägt dazu bei, dass dein MCP-Server für die Nutzenden zuverlässig bleibt.