Den vollständigen Index der Dokumentation findest du in llms.txt. Die Markdown-Version einer Dokumentationsseite erhältst du, indem du .md an die URL der Seite anhängst.
Hauptnavigation
Design

Fehlerbehebung

So behebst du Probleme mit Plugin-Tools und der optionalen Benutzeroberfläche.

Fehlerursachen eingrenzen

Wenn Komponenten nicht angezeigt werden, passende Prompts kein Tool auslösen oder die Anmeldung in einer Schleife hängen bleibt, grenze zuerst die Ursache ein. Prüfe, ob das Problem beim Server, bei der Komponente oder beim ChatGPT-Client liegt. Die folgende Checkliste zeigt dir, wie du die häufigsten Probleme behebst.

Die Hinweise zum Server, zu den Tools und zur Tool-Erkennung gelten für Plugins in ChatGPT und Codex. Die Hinweise zur Benutzeroberfläche, zum Widget-Zustand und zur Client-Authentifizierung auf dieser Seite beziehen sich auf ChatGPT.

Serverseitige Probleme

  • Keine Tools aufgelistet: Prüfe, ob dein Server läuft und du dich mit dem Endpunkt /mcp verbindest. Wenn du den Port geändert hast, aktualisiere die URL des MCP-Servers und starte MCP Inspector neu.
  • Nur strukturierte Inhalte, keine Komponente: Prüfe, ob _meta.ui.resourceUri im Tool-Deskriptor auf eine registrierte HTML-Ressource mit mimeType: "text/html;profile=mcp-app" verweist. Aus Kompatibilitätsgründen akzeptiert ChatGPT auch _meta["openai/outputTemplate"] als Alias. Prüfe außerdem, ob die Ressource ohne CSP-Fehler geladen wird.
  • Fehler durch abweichendes Schema: Stelle sicher, dass deine Python- oder TypeScript-Modelle dem in outputSchema angegebenen Schema entsprechen. Generiere die Typen nach Änderungen neu.
  • Langsame Antworten: Wenn Tool-Aufrufe länger als ein paar hundert Millisekunden dauern, reagieren Komponenten träge. Analysiere die Laufzeiten der Serveraufrufe und speichere Ergebnisse nach Möglichkeit im Cache.

Probleme mit Widgets

  • Widget lädt nicht: Öffne die Browserkonsole oder die Protokolle von MCP Inspector und suche nach CSP-Verstößen oder fehlenden Bundles. Prüfe, ob das HTML dein kompiliertes JavaScript enthält und das Bundle alle Abhängigkeiten umfasst.
  • Änderungen per Drag-and-drop oder beim Bearbeiten gehen verloren: Wenn du den Widget-Zustand über ChatGPT speicherst, rufe nach jeder Änderung window.openai.setWidgetState auf. Stelle den Zustand beim Einbinden des Widgets 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 und passe das Layout entsprechend an. Vermeide feste Höhen und Aktionen, die nur beim Überfahren mit dem Mauszeiger verfügbar sind.

Probleme mit der Tool-Erkennung und den Einstiegspunkten

  • Tool wird nie aufgerufen: Überprüfe deine Metadaten. Formuliere die Beschreibungen nach dem Muster „Verwende dieses Tool, wenn …“, aktualisiere die Einstiegsprompts und teste das Tool erneut mit deinen Referenzprompts.
  • Falsches Tool ausgewählt: Beschreibe genauer, worin sich ähnliche Tools unterscheiden, oder gib in der Beschreibung an, in welchen Fällen das Tool nicht verwendet werden darf. Prüfe, ob du umfangreiche Tools in kleinere Tools mit jeweils einem klaren Zweck aufteilen kannst.
  • Unerwartete Reihenfolge im Launcher: Aktualisiere die Metadaten im Verzeichnis. Prüfe, ob das Plugin-Symbol und die Beschreibungen den Erwartungen derjenigen entsprechen, die das Plugin nutzen.

Probleme bei der Authentifizierung

  • 401-Fehler: Füge der Fehlerantwort einen WWW-Authenticate-Header hinzu, damit ChatGPT erkennt, dass es den OAuth-Ablauf erneut starten muss. Überprüfe die Issuer-URLs und die Audience-Claims noch einmal.
  • 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 bei private_key_jwt, ob dein Autorisierungsserver das öffentliche JWKS von ChatGPT abrufen und die signierte Client-Assertion überprüfen kann. Wenn du DCR verwendest, stelle sicher, dass dein Autorisierungsserver registration_endpoint bereitstellt und für jeden neu erstellten Client 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. Falls er ein Client-Secret hat, prüfe auch, ob dein Autorisierungsserver es akzeptiert. ChatGPT verwendet dieselben Zugangsdaten erneut. Stelle sie deshalb wieder her, statt einen neuen Client zu erstellen. Bei einem abgelaufenen Zugriffstoken ist eine andere Lösung erforderlich.

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 weitergibst. Nutze für den Produktivbetrieb einen zuverlässigen Hostinganbieter mit Health Checks.
  • Streaming bricht hinter Proxys ab: Stelle sicher, dass dein Load Balancer oder CDN Server-Sent Events oder gestreamte HTTP-Antworten ohne Pufferung durchlässt.

Wann du das Problem weitergeben solltest

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

  1. Sammle die Serverprotokolle, die Ausgaben der Komponentenkonsole und das Protokoll des Tool-Aufrufs in ChatGPT. Halte das Problem auch mit Screenshots fest.
  2. Notiere den Prompt, den du eingegeben hast, und alle Bestätigungsmeldungen.
  3. Gib diese Informationen an deine Ansprechperson für die Partnerschaft bei OpenAI weiter, damit sie das Problem intern reproduzieren kann.

Ein knappes, präzises Fehlerprotokoll verkürzt die Bearbeitungszeit und hilft dir, deinen MCP-Server für alle, die ihn nutzen, zuverlässig zu betreiben.