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

Referenz

Referenz zu ChatGPT-spezifischen UI-Erweiterungen und Metadaten.

Nutze zuerst den offenen Standard. Verwende die

Spezifikation für MCP Apps

für gemeinsame UI-Felder und Bridge-Methoden. Die Erweiterungen von OpenAI sind optional. Du findest sie in window.openai, wenn du ChatGPT-spezifische Funktionen benötigst.

Komponenten-Bridge window.openai

ChatGPT stellt über window.openai Kompatibilitätsaliase und optionale ChatGPT-Erweiterungen bereit. Verwende für neue Benutzeroberflächen die Bridge von MCP Apps, wenn die gemeinsame Spezifikation eine entsprechende Funktion bietet. Greife nur für ChatGPT-spezifische Funktionen auf window.openai zurück.

Schrittweise Anleitungen zur Implementierung findest du im Leitfaden Eine ChatGPT-Oberfläche entwickeln.

Wenn dein Tool eine Bestätigung erfordert, ist es normal, dass toolInput zunächst fehlt. Vor der Genehmigung übernimmt ChatGPT genehmigungspflichtige Argumente nicht in die Widget-Werte. Der Host übermittelt sie über ui/notifications/tool-input, sobald die Person den Aufruf genehmigt hat.

Funktionen

Bereich Schnittstelle Typische Verwendung
Zustand und Daten window.openai.toolInput Argumente, die beim Aufruf des Tools übergeben wurden. Bei genehmigungspflichtigen Tools kann der Wert null bleiben, bis der Host nach der Genehmigung ui/notifications/tool-input sendet.
Zustand und Daten window.openai.toolOutput Enthält dein structuredContent. Halte die Feldinhalte knapp, da das Modell sie wortgetreu liest.
Zustand und Daten window.openai.toolResponseMetadata Maßgebliche Metadaten des Tool-Ergebnisses, die nur das Widget erhält. In ChatGPT umfassen sie status, call_tool_result und mcp_tool_result. Die vollständige MCP-Ergebnisstruktur bleibt erhalten, einschließlich des verborgenen Felds _meta.
Zustand und Daten window.openai.widgetState Gespeicherter Zustand der Benutzeroberfläche, der zwischen Rendervorgängen erhalten bleibt.
Zustand und Daten window.openai.setWidgetState(state) Speichert den neuen Zustand synchron. Rufe die Methode nach jeder relevanten Interaktion mit der Oberfläche auf.
Laufzeit-APIs für Widgets window.openai.callTool(name, args) Ruft vom Widget aus ein weiteres MCP-Tool auf, genauso wie bei einem Aufruf durch das Modell.
Laufzeit-APIs für Widgets window.openai.sendFollowUpMessage({ prompt, scrollToBottom }) Fordert ChatGPT auf, eine von der Komponente verfasste Nachricht zu posten. scrollToBottom ist optional und hat den Standardwert true. Setze den Wert auf false, um automatisches Scrollen zu verhindern.
Laufzeit-APIs für Widgets window.openai.uploadFile(file, { library?: boolean }) Lädt eine von der Person ausgewählte Datei hoch und gibt eine fileId zurück. Übergib { library: true }, um die Datei auch in der persönlichen ChatGPT-Dateibibliothek zu speichern, sofern diese verfügbar ist.
Laufzeit-APIs für Widgets window.openai.selectFiles() Öffnet die Dateiauswahl der ChatGPT-Dateibibliothek und gibt die für das Plugin freigegebenen Dateien als { fileId, fileName, mimeType }[] zurück. Prüfe, ob die Funktion vorhanden ist, da die Dateibibliothek möglicherweise nicht allen zur Verfügung steht.
Laufzeit-APIs für Widgets window.openai.getFileDownloadUrl({ fileId }) Ruft eine temporäre Download-URL für eine Datei ab. Das gilt für Dateien, die das Widget hochgeladen hat, die aus der Dateibibliothek ausgewählt oder als Dateiparameter übergeben wurden oder auf die ein Tool in seiner Rückgabe verweist.
Laufzeit-APIs für Widgets window.openai.requestDisplayMode(...) Fordert den Bild-in-Bild- oder Vollbildmodus an.
Laufzeit-APIs für Widgets window.openai.requestModal({ params, template }) Öffnet einen modalen Dialog, den ChatGPT verwaltet. Lass template weg, um die aktuelle Vorlage zu verwenden, oder übergib die URI einer registrierten Vorlage, um den Dialoginhalt zu wechseln.
Laufzeit-APIs für Widgets window.openai.requestClose() Fordert ChatGPT auf, das aktuelle Widget zu schließen.
Laufzeit-APIs für Widgets window.openai.notifyIntrinsicHeight(...) Meldet die Höhe des Widgets, wenn sie sich ändert, damit beim Scrollen keine Inhalte abgeschnitten werden.
Laufzeit-APIs für Widgets window.openai.openExternal({ href, redirectUrl }) Öffnet einen geprüften externen Link im Browser der Person. Bei genehmigten Weiterleitungszielen hängt ChatGPT standardmäßig ?redirectUrl=... an. Mit redirectUrl: false unterbindest du das.
Laufzeit-APIs für Widgets window.openai.setOpenInAppUrl({ href }) Überschreibt bei Bedarf das im Vollbildmodus angezeigte externe Ziel. Ohne diese Angabe öffnet ChatGPT standardmäßig den aktuellen iframe-Pfad der Komponente.
Kontext window.openai.theme, window.openai.displayMode, window.openai.maxHeight, window.openai.safeArea, window.openai.view, window.openai.userAgent, window.openai.locale Umgebungsinformationen, die du über useOpenAiGlobal auslesen oder abonnieren kannst, um Darstellung und Texte anzupassen.

Hilfsfunktion useOpenAiGlobal

Viele Projekte für ChatGPT-Oberflächen kapseln den Zugriff auf window.openai in kleinen Hilfsfunktionen, damit sich die Ansichten testen lassen. Die folgende Hilfsfunktion reagiert auf openai:set_globals-Ereignisse des Hosts. Damit können React-Komponenten Änderungen an einem einzelnen globalen Wert abonnieren.

import { useSyncExternalStore } from "react";

type WebplusGlobals = {
  widgetState: { selectedId?: string | null; [key: string]: unknown } | null;
  toolInput: Record<string, unknown>;
  toolOutput: Record<string, unknown> | null;
  theme: "light" | "dark";
};
const SET_GLOBALS_EVENT_TYPE = "openai:set_globals";

export function useOpenAiGlobal<K extends keyof WebplusGlobals>(
  key: K
): WebplusGlobals[K] {
  return useSyncExternalStore(
    (onChange) => {
      const handleSetGlobal = (event: Event) => {
        if (!(event instanceof CustomEvent)) return;
        const value = event.detail?.globals?.[key];
        if (value === undefined) {
          return;
        }

        onChange();
      };

      window.addEventListener(SET_GLOBALS_EVENT_TYPE, handleSetGlobal, {
        passive: true,
      });

      return () => {
        window.removeEventListener(SET_GLOBALS_EVENT_TYPE, handleSetGlobal);
      };
    },
    () => {
      const globals = (window as Window & { openai?: WebplusGlobals }).openai;
      if (!globals) throw new Error("This hook requires a ChatGPT app host.");
      return globals[key];
    }
  );
}

Oberfläche schließen

Rufe window.openai.requestClose() auf, um ChatGPT aufzufordern, die aktuelle Oberfläche zu schließen.

Einen anderen Anzeigemodus anfordern

Mit window.openai.requestDisplayMode kannst du die Inline-Darstellung, den Bild-in-Bild-Modus oder den Vollbildmodus anfordern.

await window.openai?.requestDisplayMode({ mode: "fullscreen" });
// On mobile, picture-in-picture may be presented as fullscreen.

Einen modalen Dialog öffnen

Mit window.openai.requestModal öffnest du einen modalen Dialog, den der Host steuert. Gib die URI einer anderen UI-Vorlage an, die derselbe MCP-Server registriert hat, oder lass template weg, um die aktuelle Vorlage zu öffnen.

await window.openai.requestModal({
  template: "ui://widget/details.html",
});

Datei-APIs

ChatGPT bietet Hilfsfunktionen zum Hoch- und Herunterladen von Dateien als optionale Erweiterungen von window.openai an.

API Zweck Hinweise
window.openai.uploadFile(file, { library?: boolean }) Lädt eine von der Person ausgewählte Datei hoch und gibt eine fileId zurück. Übergib { library: true }, um die Datei auch in der persönlichen ChatGPT-Dateibibliothek zu speichern, sofern die Person Zugriff auf diese Bibliothek hat.
window.openai.selectFiles() Öffnet die Dateiauswahl für vorhandene Dateien in der Bibliothek. Gibt [{ fileId, fileName, mimeType }] zurück. Prüfe, ob die Funktion vorhanden ist, da die Dateibibliothek möglicherweise nicht allen zur Verfügung steht.
window.openai.getFileDownloadUrl({ fileId }) Fordert eine temporäre Download-URL für eine Datei an. Funktioniert mit Dateien, die das Widget hochgeladen hat, die aus der Dateibibliothek ausgewählt oder als Dateiparameter übergeben wurden oder auf die ein Tool in seiner Rückgabe verweist.

Die ChatGPT-Dateibibliothek ist optional und steht möglicherweise nicht allen zur Verfügung. Wenn window.openai.selectFiles() verfügbar ist, sind die zurückgegebenen Dateien bereits für das aktuelle Plugin freigegeben. Verwende die zurückgegebene fileId mit window.openai.getFileDownloadUrl({ fileId }) oder in einer Tool-Eingabe, die Dateiparameter verwendet.

So lädst du eine von der Person ausgewählte Datei hoch:

const { fileId } = await window.openai.uploadFile(file, {
  library: true,
});

So wählst du Dateien aus, die die Person bereits in ChatGPT hochgeladen hat:

if (window.openai?.selectFiles) {
  const files = await window.openai.selectFiles();
  // [{ fileId, fileName, mimeType }]
}

Prüfe, ob window.openai.selectFiles vorhanden ist, und verwende window.openai.uploadFile, wenn die Dateibibliothek nicht verfügbar ist.

So forderst du eine temporäre Download-URL an:

const { downloadUrl } = await window.openai.getFileDownloadUrl({ fileId });

Dateieingaben definieren

Damit ChatGPT Dateien an ein Tool übergeben kann, führe jedes Dateieingabefeld der obersten Ebene in _meta["openai/fileParams"] auf. Jedes dieser Felder muss ein Dateiobjekt oder ein Array von Dateiobjekten enthalten.

Im Schema jedes Dateiobjekts musst du alle vier unterstützten Eigenschaften deklarieren:

Eigenschaft Typ In properties deklarieren In required aufnehmen
download_url string Ja Ja
file_id string Ja Ja
mime_type string Ja Nein
file_name string Ja Nein

Für mime_type und file_name sind die Werte optional. Die Eigenschaften selbst musst du im Schema deklarieren. Sowohl im Schritt Scan Tools als auch bei der Plugin-Einreichung wird ein Dateischema abgelehnt, wenn eine der vier Eigenschaften fehlt, wenn download_url und file_id nicht beide Pflichtfelder sind, wenn eine der optionalen Eigenschaften als Pflichtfeld markiert ist oder wenn eine andere Eigenschaft als download_url oder file_id erforderlich ist. Du kannst weitere optionale Eigenschaften deklarieren.

Dieser vollständige Tool-Deskriptor erwartet eine Datei als Pflichteingabe:

{
  "name": "analyze_file",
  "title": "Analyze file",
  "description": "Analyzes a user-provided file without modifying it.",
  "inputSchema": {
    "type": "object",
    "$defs": {
      "OpenAIFile": {
        "type": "object",
        "properties": {
          "download_url": { "type": "string" },
          "file_id": { "type": "string" },
          "mime_type": { "type": "string" },
          "file_name": { "type": "string" }
        },
        "required": ["download_url", "file_id"],
        "additionalProperties": false
      }
    },
    "properties": {
      "file": { "$ref": "#/$defs/OpenAIFile" }
    },
    "required": ["file"]
  },
  "annotations": {
    "readOnlyHint": true,
    "openWorldHint": false,
    "destructiveHint": false
  },
  "_meta": {
    "openai/fileParams": ["file"]
  }
}

Wenn das Tool mehrere Dateien annehmen soll, definiere das Feld auf der obersten Ebene als Array und verwende in items dasselbe Schema für die Dateiobjekte. Ob das Dateifeld auf der obersten Ebene ein Pflichtfeld ist, kannst du unabhängig von den Pflichtfeldern der einzelnen Dateiobjekte festlegen.

Zur Laufzeit übergibt ChatGPT die Dateidaten mit Feldnamen in Snake Case:

{
  "download_url": "https://...",
  "file_id": "file_...",
  "mime_type": "image/png",
  "file_name": "input.png"
}

ChatGPT übergibt immer download_url und file_id. Die Felder mime_type und file_name können fehlen. Wenn ein Widget eine neue temporäre Download-URL benötigt, übergib file_id als Wert für fileId an window.openai.getFileDownloadUrl({ fileId }).

Wenn du den Widget-Zustand speicherst und das Modell in späteren Gesprächsschritten auf die Bild-IDs zugreifen soll, verwende das strukturierte Format (modelContent, privateContent, imageIds).

Die Sandbox-Laufzeit überträgt den Navigationsverlauf des iframes in die ChatGPT-Oberfläche. Verwende gängige Routing-APIs wie React Router. Der Host hält seine Navigationselemente dann mit deiner Oberfläche synchron.

So richtest du das Routing mit dem BrowserRouter von React Router ein:

import {
  BrowserRouter,
  Routes,
  Route,
  Link,
  useParams,
} from "react-router-dom";
function PizzaListPlugin() {
  const { placeId } = useParams();
  return (
    <main>
      <Link to="/place/pizzeria">Example Pizzeria</Link>
      <p>{placeId ?? "Choose a place"}</p>
    </main>
  );
}

export default function PizzaListRouter() {
  return (
    <BrowserRouter>
      <Routes>
        <Route path="/" element={<PizzaListPlugin />}>
          <Route path="place/:placeId" element={<PizzaListPlugin />} />
        </Route>
      </Routes>
    </BrowserRouter>
  );
}

So steuerst du die Navigation im Code:

import { createElement } from "react";
import { BrowserRouter, useNavigate } from "react-router-dom";
function NavigationExample() {
  const navigate = useNavigate();

  function openDetails(placeId: string) {
    navigate(`place/${placeId}`, { replace: false });
  }

  function closeDetails() {
    navigate("..", { replace: true });
  }

  return createElement(
    "div",
    null,
    createElement(
      "button",
      { onClick: () => openDetails("pizzeria") },
      "Open details"
    ),
    createElement("button", { onClick: closeDetails }, "Close details")
  );
}

Parameter des Tool-Deskriptors

Eine Tool-Beschreibung sollte standardmäßig die Felder enthalten, die in der MCP-Spezifikation aufgeführt sind.

Deklariere outputSchema für jedes Tool, das structuredContent zurückgibt. Das Schema sollte das zurückgegebene Objekt genau beschreiben. So können Clients die Ergebnisse validieren und das Modell kann beurteilen, welche weiteren Tool-Aufrufe sinnvoll sind.

_meta-Felder im Tool-Deskriptor

Verwende die folgenden _meta-Felder im Tool-Deskriptor. Nutze vorzugsweise den Standardschlüssel _meta.ui.resourceUri von MCP Apps, um ein Tool mit einer UI-Vorlage zu verknüpfen. ChatGPT unterstützt OpenAI-spezifische Metadaten für die Kompatibilität und für optionale Erweiterungen.

Schlüssel Position Typ Einschränkungen Zweck
_meta["securitySchemes"] Tool-Deskriptor array Keine Kopie der Sicherheitsschemata für die Abwärtskompatibilität mit Clients, die nur _meta lesen.
_meta.ui.resourceUri Tool-Deskriptor string (URI) Keine Standard-Ressourcen-URI der UI-Vorlage.
_meta.ui.visibility Tool-Deskriptor string[] Standardwert ["model", "app"] Legt fest, ob ein Tool dem Modell, der Oberfläche oder beiden zur Verfügung steht. Der Wert app bezeichnet im Protokoll von MCP Apps die Oberfläche.
_meta["openai/outputTemplate"] Tool-Deskriptor string (URI) Keine Optionaler OpenAI-spezifischer Alias für _meta.ui.resourceUri, den ChatGPT aus Kompatibilitätsgründen unterstützt.
_meta["openai/profile"] Tool-Deskriptor boolean Optional. Nur true kennzeichnet ein Profil-Tool. Kennzeichnet das authentifizierte Tool ohne Schreibzugriff, das das aktuelle Profil zurückgibt. Implementiere es, damit sich mehrere verbundene Konten leichter unterscheiden und verwalten lassen. Auch ohne dieses Tool lassen sich mehrere Konten verbinden. Siehe Mehrere Konten unterstützen.
_meta["openai/widgetAccessible"] Tool-Deskriptor boolean Standardwert false OpenAI-spezifisches Kompatibilitätsfeld für bestehende UI-Integrationen. Verwende vorzugsweise _meta.ui.visibility in Verbindung mit tools/call.
_meta["openai/visibility"] Tool-Deskriptor string public (Standardwert) oder private OpenAI-spezifisches Kompatibilitätsfeld für bestehende UI-Integrationen. Verwende vorzugsweise _meta.ui.visibility.
_meta["openai/toolInvocation/invoking"] Tool-Deskriptor string ≤ 64 Zeichen Kurzer Statustext während der Tool-Ausführung.
_meta["openai/toolInvocation/invoked"] Tool-Deskriptor string ≤ 64 Zeichen Kurzer Statustext nach Abschluss der Tool-Ausführung.
_meta["openai/fileParams"] Tool-Deskriptor string[] Keine Liste der Eingabefelder auf der obersten Ebene, die Dateien repräsentieren. Jedes Feld erhält { download_url, file_id, mime_type?, file_name? }.

Beispiel:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
const server = new McpServer({ name: "docs-example", version: "1.0.0" });

// Local example data; replace this with your application data.
async function performSearch(query: string) {
  const documents = [
    {
      id: "intro",
      title: "Introduction to Acme",
      url: "https://example.com/intro",
    },
  ];
  return documents.filter((document) =>
    document.title.toLowerCase().includes(query.toLowerCase())
  );
}

import { registerAppTool } from "@modelcontextprotocol/ext-apps/server";
import { z } from "zod";

registerAppTool(
  server,
  "search",
  {
    title: "Public Search",
    description: "Search public documents.",
    inputSchema: { q: z.string() },
    outputSchema: {
      results: z.array(
        z.object({
          id: z.string(),
          title: z.string(),
          url: z.string(),
        })
      ),
    },
    _meta: {
      securitySchemes: [
        { type: "noauth" },
        { type: "oauth2", scopes: ["search.read"] },
      ],
      ui: { resourceUri: "ui://widget/story.html" },
      // Optional compatibility alias (ChatGPT only):
      // "openai/outputTemplate": "ui://widget/story.html",
      "openai/toolInvocation/invoking": "Searching…",
      "openai/toolInvocation/invoked": "Results ready",
    },
  },
  async ({ q }) => {
    const results = await performSearch(q);

    return {
      structuredContent: { results },
      content: [{ type: "text", text: `Found ${results.length} results.` }],
    };
  }
);

Annotationen

Um ein Tool als „ohne Schreibzugriff“ zu kennzeichnen, verwende im Tool-Deskriptor die folgenden ToolAnnotations-Felder:

Schlüssel Typ Pflichtfeld Hinweise
readOnlyHint boolean Ja Gibt an, dass das Tool ausschließlich Informationen abruft oder berechnet. Es erstellt, aktualisiert oder löscht keine Daten und sendet keine Daten aus der Unterhaltung heraus.
destructiveHint boolean Ja Gibt an, dass das Tool Nutzerdaten löschen oder überschreiben kann. So weiß der Host, dass er vorher eine ausdrückliche Genehmigung einholen muss.
openWorldHint boolean Ja Gibt an, dass das Tool auf das öffentliche Internet oder auf externe Ressourcen ohne feste Eingrenzung zugreift. Dazu zählen auch Aktionen ohne Schreibzugriff wie die Websuche. Ein privates Konto oder ein Workspace mit klar begrenztem Umfang fällt nicht allein deshalb darunter, weil das Hosting extern erfolgt.
idempotentHint boolean Nein Gibt an, dass ein erneuter Tool-Aufruf mit denselben Argumenten keine zusätzliche Auswirkung auf die Umgebung hat.

Diese Hinweise beeinflussen lediglich, wie ChatGPT oder Codex den Tool-Aufruf in der Benutzeroberfläche darstellt. Server müssen weiterhin ihre eigenen Autorisierungsregeln durchsetzen.

Beispiel:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
const server = new McpServer({ name: "docs-example", version: "1.0.0" });

// Local example data; replace this with your application data.
async function fetchSavedRecipes() {
  return [{ id: "pasta", title: "Tomato pasta" }];
}

import { z } from "zod";

server.registerTool(
  "list_saved_recipes",
  {
    title: "List saved recipes",
    description: "Returns the user’s saved recipes without modifying them.",
    inputSchema: {},
    outputSchema: {
      recipes: z.array(
        z.object({
          id: z.string(),
          title: z.string(),
        })
      ),
    },
    annotations: { readOnlyHint: true },
  },
  async () => ({
    content: [],
    structuredContent: { recipes: await fetchSavedRecipes() },
  })
);

_meta-Felder der Komponentenressource

Setze diese Schlüssel in der Ressourcenvorlage, die deine Komponente bereitstellt (registerResource). Damit kann ChatGPT den dargestellten iframe beschreiben und passend einbetten, ohne Metadaten gegenüber anderen Clients offenzulegen.

Schlüssel Position Typ Zweck
_meta.ui.prefersBorder Ressourceninhalt boolean Gibt an, dass die Komponente nach Möglichkeit in einer Karte mit Rahmen erscheinen soll.
_meta.ui.csp Ressourceninhalt object Hier solltest du die standardisierten CSP-Felder des Widgets angeben: connectDomains, resourceDomains und optional frameDomains.
_meta.ui.domain Ressourceninhalt string (Origin) Eigener Origin für gehostete Komponenten. Er ist bei der Einreichung eines Plugins mit Benutzeroberfläche erforderlich und muss für jedes Plugin eindeutig sein. Der Standardwert ist https://web-sandbox.oaiusercontent.com.
_meta["openai/ui"].availableDisplayModes Ressourceninhalt string[] Unterstützte Anzeigemodi: inline, fullscreen und pip. Damit kann ChatGPT den Anzeigemodus wählen, bevor die Komponente geladen wird.
_meta["openai/widgetDescription"] Ressourceninhalt string Verständliche Zusammenfassung, die das Modell beim Laden der Komponente erhält. So muss der Assistent bereits sichtbare Inhalte seltener nochmals beschreiben.
_meta["openai/widgetPrefersBorder"] Ressourceninhalt boolean OpenAI-spezifischer Kompatibilitätsalias für _meta.ui.prefersBorder in ChatGPT.
_meta["openai/widgetCSP"] Ressourceninhalt object Älterer ChatGPT-Kompatibilitätsschlüssel für die CSP-Metadaten des Widgets. Für die standardisierten CSP-Felder ersetzt ihn _meta.ui.csp. Das Feld redirect_domains ist weiterhin erforderlich, um vertrauenswürdige Weiterleitungsziele für openExternal anzugeben.
_meta["openai/widgetDomain"] Ressourceninhalt string (Origin) OpenAI-spezifischer Kompatibilitätsalias für _meta.ui.domain in ChatGPT.

ChatGPT unterstützt den älteren Kompatibilitätsschlüssel _meta["openai/widgetCSP"] mit folgenden Feldnamen in snake_case:

  • connect_domains: string[]
  • resource_domains: string[]
  • frame_domains?: string[]
  • redirect_domains?: string[]. ChatGPT-Erweiterung für Weiterleitungsziele von window.openai.openExternal.

Für neue Oberflächen empfiehlt sich in der Regel das Standardobjekt _meta.ui.csp. Es unterstützt folgende Felder:

  • connectDomains: string[]. Domains, die das Widget über Fetch oder XHR kontaktieren darf.
  • resourceDomains: string[]. Domains für statische Ressourcen wie Bilder, Schriftarten, Skripte und Stylesheets.
  • frameDomains?: string[]. Optionale Liste zulässiger Origins für iframe-Einbettungen. Standardmäßig können Widgets keine untergeordneten Frames darstellen. Nach der iframe-Richtlinie dürfen Plugins Inhalte ihrer eigenen Domain einbetten, darunter vorhandene Editoren und Verwaltungsoberflächen. Bei der Einreichung musst du die Einbettung begründen. Der Einsatz von iframes kann eine zusätzliche Prüfung erfordern oder die Genehmigung verzögern.

Allerdings unterstützt _meta.ui.csp das Feld redirect_domains für Links über window.openai.openExternal(...) nicht. Um Weiterleitungsziele ausdrücklich zuzulassen, musst du weiterhin _meta["openai/widgetCSP"].redirect_domains setzen.

Anzeigemodi vor dem Laden der Oberfläche deklarieren

Setze _meta["openai/ui"].availableDisplayModes im Ressourceninhalt, den dein Server zurückgibt. Unterstützt eine Komponente ausschließlich den Vollbildmodus, kann ChatGPT sie so direkt im Vollbild öffnen, ohne vorher eine Inline-Ladeansicht anzuzeigen.

Gib dieses Objekt im Array contents der Ressource zurück. Setze html auf den HTML-Code deiner Komponente:

const resource = {
  uri: "ui://widget/viewer.html",
  mimeType: "text/html;profile=mcp-app",
  text: html,
  _meta: {
    "openai/ui": {
      availableDisplayModes: ["fullscreen"],
    },
  },
};

Führe alle Modi auf, die deine Komponente unterstützt, etwa ["inline", "fullscreen"]. Deklariere availableDisplayModes weiterhin auch bei der Initialisierung von MCP Apps. Die serverseitige Deklaration ergänzt diesen Ablauf, der auch dynamische Anzeigemodi unterstützt.

Tool-Ergebnisse

Tool-Ergebnisse können die in der Spezifikation beschriebenen Felder enthalten. Besonders relevant sind die folgenden:

Schlüssel Typ Pflichtfeld Hinweise
structuredContent object Nein Für Modell und Komponente sichtbar. Muss dem deklarierten outputSchema entsprechen, sofern eines angegeben ist.
content string oder Content[] Nein Für Modell und Komponente sichtbar.
_meta object Nein Nur die Komponente erhält dieses Feld. Für das Modell bleibt es verborgen.

Im Gesprächsverlauf erscheinen nur structuredContent und content. Der Host leitet _meta an die Komponente weiter. So kannst du die Oberfläche mit Daten befüllen, ohne sie dem Modell offenzulegen.

Metadaten, die der Host für Tool-Ergebnisse bereitstellt:

Schlüssel Position Typ Zweck
_meta["openai/widgetSessionId"] _meta des Tool-Ergebnisses (vom Host) string Stabile ID der aktuell eingebundenen Widget-Instanz. Damit kannst du Protokolleinträge und Tool-Aufrufe einander zuordnen, bis das Widget aus der Oberfläche entfernt wird.

Beispiel:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
const server = new McpServer({ name: "docs-example", version: "1.0.0" });

// Local example data; replace this with your application data.
function generateZooAnimals(count: number) {
  return Array.from({ length: count }, (_, index) => ({
    id: `animal-${index + 1}`,
    name: `Penguin ${index + 1}`,
    species: "Penguin",
  }));
}

import { registerAppTool } from "@modelcontextprotocol/ext-apps/server";
import { z } from "zod";

registerAppTool(
  server,
  "get_zoo_animals",
  {
    title: "get_zoo_animals",
    inputSchema: { count: z.number().int().min(1).max(20).optional() },
    outputSchema: {
      animals: z.array(
        z.object({
          id: z.string(),
          name: z.string(),
          species: z.string(),
        })
      ),
    },
    _meta: { ui: { resourceUri: "ui://widget/widget.html" } },
  },
  async ({ count = 10 }) => {
    const animals = generateZooAnimals(count);

    return {
      structuredContent: { animals },
      content: [{ type: "text", text: `Here are ${animals.length} animals.` }],
      _meta: {
        allAnimalsById: Object.fromEntries(
          animals.map((animal) => [animal.id, animal])
        ),
      },
    };
  }
);

Fehler im Tool-Ergebnis

Um einen Fehler im Tool-Ergebnis zurückzugeben, verwende den folgenden _meta-Schlüssel:

Schlüssel Zweck Typ Hinweise
_meta["mcp/www_authenticate"] Fehlerrückgabe string oder string[] Authentifizierungsaufforderungen gemäß RFC 7235 über WWW-Authenticate, die OAuth auslösen.

Vom Client bereitgestellte _meta-Felder

Schlüssel Zeitpunkt der Übermittlung Typ Zweck
_meta["openai/locale"] Initialisierung und Tool-Aufrufe string (BCP 47) Angeforderte Spracheinstellung. Ältere Clients senden möglicherweise _meta["webplus/i18n"].
_meta["openai/userAgent"] Tool-Aufrufe string Optionaler Hinweis zum User-Agent für Analysen oder zur Formatierung, soweit er sich ermitteln lässt.
_meta["openai/userLocation"] Tool-Aufrufe object Ungefähre Standortangaben (city, region, country, timezone, longitude, latitude).
_meta["openai/subject"] Tool-Aufrufe string Anonymisierte Nutzer-ID, die MCP-Server zur Ratenbegrenzung und Identifizierung erhalten.
_meta["openai/session"] Tool-Aufrufe string Anonymisierte Gesprächs-ID, mit der sich Tool-Aufrufe innerhalb derselben ChatGPT-Sitzung einander zuordnen lassen.
_meta["openai/organization"] Tool-Aufrufe string Anonymisierte Organisations-ID der aktuellen ChatGPT-Organisation, sofern verfügbar.

Bei der Ausführung dienen _meta["openai/userAgent"] und _meta["openai/userLocation"] nur als Hinweise. Server dürfen Autorisierungsentscheidungen nie auf diese Angaben stützen und müssen auch ohne sie funktionieren. Behandle _meta["openai/userAgent"] als optionale Metadaten, die der Client nach Möglichkeit liefert. Daraus lässt sich nicht zuverlässig erkennen, welche Host-Oberfläche deinen Server aufruft.

Beispiel:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
const server = new McpServer({ name: "docs-example", version: "1.0.0" });

// Local example data; replace this with your application data.
async function findNearbyCafes(city: unknown) {
  return city === "San Francisco"
    ? [{ name: "Example Cafe", address: "123 Example Street, San Francisco" }]
    : [];
}

function formatIntro(locale: unknown, city: unknown) {
  const location = typeof city === "string" ? city : "your area";
  return locale === "es" ? `Cafés en ${location}` : `Cafes in ${location}`;
}

import { z } from "zod";

server.registerTool(
  "recommend_cafe",
  {
    title: "Recommend a cafe",
    inputSchema: {},
    outputSchema: {
      cafes: z.array(
        z.object({
          name: z.string(),
          address: z.string(),
        })
      ),
    },
  },
  async (_args, { _meta }) => {
    const locale = _meta?.["openai/locale"] ?? "en";
    const userLocation = _meta?.["openai/userLocation"];
    const location =
      typeof userLocation === "object" &&
      userLocation !== null &&
      "city" in userLocation
        ? userLocation.city
        : undefined;
    const cafes = await findNearbyCafes(location);

    return {
      content: [{ type: "text", text: formatIntro(locale, location) }],
      structuredContent: { cafes },
    };
  }
);