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

Deinen MCP-Server um eine Benutzeroberfläche erweitern

Gib für ausgewählte MCP-Tools optional UI-Ressourcen zurück.

Überblick

Eine eigene Benutzeroberfläche (UI) ist optional. Ergänze sie, wenn Menschen mit deinem Plugin strukturierte Informationen prüfen, vergleichen, bearbeiten oder bestätigen oder durch diese Informationen navigieren müssen. Gestalte die MCP-Tools so, dass sie auch ohne Komponente nutzbar sind. So können ChatGPT und Codex den Ablauf auch ohne UI abschließen.

Der MCP-Server gibt für ausgewählte Tools UI-Ressourcen zurück. Die Komponenten laufen in ChatGPT in einem iframe, kommunizieren über die Bridge von MCP Apps mit dem Host (JSON-RPC über postMessage) und erscheinen neben der Unterhaltung. Dank des offenen Standards MCP Apps kann dieselbe UI auf verschiedenen kompatiblen Hosts laufen.

Mit MCP Apps beginnen

ChatGPT implementiert den offenen Standard MCP Apps für Benutzeroberflächen, die ein MCP-Server zurückgibt. MCP Apps legt fest, wie dein Server Tools mit UI-Ressourcen verknüpft und wie der iframe mit seinem Host kommuniziert.

So gehst du bei einer neuen UI vor:

  1. Deklariere die UI-Ressource mit _meta.ui.resourceUri.
  2. Verwende die JSON-RPC-Bridge ui/* über postMessage für die Initialisierung, Benachrichtigungen, Toolaufrufe, Nachrichten und den für das Modell sichtbaren Kontext.
  3. Gestalte die Tools so, dass sie auch ohne UI nutzbar sind. So kann das Modell den Ablauf auch in Clients abschließen, die keine Komponenten darstellen.

Auf dieser Grundlage kann dieselbe UI in ChatGPT und auf anderen Hosts laufen, die MCP Apps unterstützen.

Für die Implementierung findest du die Details in der Spezifikation für MCP Apps.

Informationen zu Apps in der Seitenleiste, zur Dateianzeige und zu umfangreicheren Formularen findest du im Abschnitt Erweiterungen.

ChatGPT-Erweiterungen ergänzen

Sobald der Ablauf mit MCP Apps funktioniert, verwende window.openai nur für Funktionen, die die gemeinsame Spezifikation nicht abdeckt. Mit diesen optionalen Erweiterungen kannst du die Bedienung in ChatGPT verbessern. Die portable UI bleibt unabhängig davon.

Gemeinsame Felder und Methoden bevorzugen

Wenn die gemeinsame Spezifikation eine Funktion abdeckt, verwende das entsprechende Feld oder die entsprechende Methode von MCP Apps:

Ziel Standard von MCP Apps Kompatibilitätsalias in ChatGPT
Tool mit einer UI-Ressource verknüpfen _meta.ui.resourceUri _meta["openai/outputTemplate"]
Tooleingaben empfangen ui/initialize + ui/notifications/tool-input window.openai.toolInput
Toolergebnisse empfangen ui/notifications/tool-result window.openai.toolOutput
Tool aus der UI aufrufen tools/call window.openai.callTool
Folgenachricht senden ui/message window.openai.sendFollowUpMessage

Die Kompatibilitätsaliase bleiben für bestehende Integrationen verfügbar. Verwende für neue Benutzeroberflächen die gemeinsamen Felder und Bridge-Methoden aus der mittleren Spalte.

Beispiele für Erweiterungen:

  • Instant Checkout mit window.openai.requestCheckout.
  • Dateiverarbeitung in ChatGPT mit window.openai.uploadFile, window.openai.selectFiles und window.openai.getFileDownloadUrl.
  • Vom Host gesteuerte modale Dialoge mit window.openai.requestModal.
  • Speichern des Widget-Zustands mit window.openai.widgetState und window.openai.setWidgetState.

Prüfe für jede Erweiterung, ob sie verfügbar ist, und biete nach Möglichkeit eine Alternative an:

const openai = typeof window !== "undefined" ? window.openai : undefined;

if (openai?.requestModal) {
  await openai.requestModal({
    template: "ui://widget/details.html",
  });
} else {
  document.body.textContent = "This host does not support modals.";
}

Mach den Programmablauf nicht vom Namen des Hosts oder Produkts abhängig. Prüfe direkt, ob die benötigte Funktion verfügbar ist.

Signaturen und Beispiele für die Erweiterungen findest du in der Referenz zur Komponenten-Bridge window.openai.

Optionale Komponentenbibliothek von OpenAI

Die Komponentenbibliothek @openai/apps-sdk-ui enthält fertige Schaltflächen, Karten, Eingabeelemente und Layout-Bausteine, die zum UI-Container von ChatGPT passen. Damit kannst du deine UI einheitlich gestalten, ohne die Basiskomponenten selbst zu entwickeln.

Weitere Beispiele findest du im Repository mit UI-Beispielen auf GitHub.

Darstellungsform wählen

Beginne mit einer Inline-Ansicht und fordere erst dann mehr Platz an, wenn der Ablauf ihn erfordert. Wähle die kleinste Ansicht, in der sich das Ergebnis nachvollziehen oder die Aufgabe erledigen lässt.

Inline-Karte

Verwende eine Inline-Karte für ein einzelnes Ergebnis, eine Bestätigung oder wenige Aktionen. Die Karte sollte für sich verständlich sein und ohne verschachtelte Navigation auskommen.

Beispiele für Inline-Karten

Inline-Karussell

Verwende ein Inline-Karussell, wenn mehrere ähnliche Optionen mit vielen visuellen Details zur Auswahl stehen und sich auf einen Blick vergleichen lassen sollen. Halte die Auswahl klein.

Beispiel für ein Inline-Karussell

Vollbild

Verwende die Vollbildansicht für Aufgaben, die mehr Platz benötigen, etwa für Karten, grafische Arbeitsflächen oder das Durchsehen detaillierter Inhalte. Gestalte die UI so, dass sie mit dem Texteingabefeld von ChatGPT zusammenarbeitet. Es bleibt auch im Vollbild verfügbar.

Beispiel für eine UI im Vollbild

Bild-in-Bild

Verwende die Bild-in-Bild-Ansicht für Aktivitäten, die während der Unterhaltung sichtbar bleiben sollen, etwa eine Livesitzung, ein Spiel oder ein Video.

Beispiel für eine Bild-in-Bild-Ansicht

Ausführliche Empfehlungen zu Layout, Interaktion, visueller Gestaltung und Barrierefreiheit findest du in den UI-Richtlinien.

Datenverarbeitung und UI-Darstellung trennen

Tools entkoppeln

Wenn du jedem Toolaufruf eine Widget-Vorlage mitgibst, rendert ChatGPT deinen iframe möglicherweise zu oft neu. Trenne deshalb die Tools für die Datenverarbeitung von denen für die Darstellung:

  • Datentools rufen Daten ab, berechnen oder ändern sie und geben ausschließlich Toolergebnisse zurück.
  • Render-Tools übernehmen die fertig aufbereiteten Daten und geben die Widget-Vorlage zurück.

So kann das Modell die abgerufenen Daten auswerten, bevor es entscheidet, ob es eine UI anzeigt. Damit steigt die Wahrscheinlichkeit deutlich, dass es das ausdrücklich genannte Ziel erreicht.

Diese Trennung ist Teil der Architektur von MCP Apps.

In der Praxis teilen viele UI-Integrationen die Arbeit so auf:

  • Tools zum Suchen und Abrufen von Daten: Sie geben IDs und Metadaten ohne Widget-Vorlage zurück.
  • Render-Tools (zum Beispiel render_listings_widget): Sie übernehmen eine vorbereitete Liste von IDs und rendern das Widget.

Nur das Render-Tool sollte _meta.ui.resourceUri enthalten.

Ablauf bei getrennten Toolaufrufen

Empfohlener Ablauf:

  1. Das Modell ruft das Datentool auf (zum Beispiel roll_dice).
  2. Das Modell erhält structuredContent vom Datentool.
  3. Das Modell ruft das Render-Tool mit diesen Daten auf.
  4. Das Widget wird einmal mit dem endgültigen, vom Modell geprüften Kontext gerendert.

Beispiel: Rückfragen zu Immobilienangeboten

Angenommen, dein Plugin zeigt Immobilienangebote als Karten sowie auf einer Landkarte an. Dein serverseitiges Tool search unterstützt nur allgemeine Filter wie Stadt, Preis und Anzahl der Schlaf- und Badezimmer. Nach Schuleinzugsgebiet kann es nicht filtern.

Bei einer Rückfrage wie „Welche dieser Immobilien liegen im Einzugsgebiet der Richmond Primary School?“ hilft die Trennung der Tools:

  1. search führt eine allgemeine Suche aus und gibt die IDs und Metadaten der infrage kommenden Angebote zurück.
  2. Das Modell grenzt die Auswahl anhand der Rückfrage ein.
  3. Das Modell ruft render_listings_widget nur mit den IDs der passenden Angebote auf.
  4. Das Widget zeigt die gefilterte Auswahl an.

Bewährte Vorgehensweisen:

  • Gestalte Datentools so, dass sie wiederverwendbar sind. Gib in structuredContent alle Daten zurück, die für nachfolgende Toolaufrufe benötigt werden.
  • Beschränke Render-Tools auf die Darstellung. Halte die Geschäftslogik aus dem Render-Handler heraus.
  • Nenne die Abhängigkeit in der Beschreibung des Render-Tools (zum Beispiel „Rufe immer zuerst roll_dice auf“).
  • Führe Tools nur gezielt erneut aus. Lass die UI bei lokalen Aktionen wie „Erneut würfeln“ direkt das Datentool aufrufen, ohne das Widget neu zu mounten.

Beispiel für entkoppelte Tools

Zwei getrennte Tools zum Würfeln und zur Anzeige des Ergebnisses:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod/v3";
import { build } from "esbuild";
import { fileURLToPath } from "node:url";

const TEMPLATE_URI = "ui://widget/dice.html";

const server = new McpServer(
  { name: "Decoupled dice", version: "1.0.0" },
  { capabilities: { tools: {} } }
);

// Bundle the same browser source that is type-checked and tested directly.
const widgetBundle = await build({
  entryPoints: [fileURLToPath(new URL("./dice-widget.ts", import.meta.url))],
  bundle: true,
  format: "esm",
  platform: "browser",
  write: false,
});
const widgetScript = widgetBundle.outputFiles[0].text.replace(
  /<\/script/gi,
  "<\\/script"
);
const widgetHtml = `<!doctype html><html lang="en"><meta charset="utf-8"><title>Dice widget</title><body><script type="module">${widgetScript}</script></body></html>`;

server.registerResource("dice-widget", TEMPLATE_URI, {}, async () => ({
  contents: [
    {
      uri: TEMPLATE_URI,
      mimeType: "text/html;profile=mcp-app",
      text: widgetHtml,
      _meta: { ui: { prefersBorder: true } },
    },
  ],
}));

// 1) Data tool: no output template, returns chainable structuredContent.
server.registerTool(
  "roll_dice",
  {
    title: "Roll dice",
    description: "Roll an N-sided die and return { sides, value }.",
    inputSchema: { sides: z.number().int().min(2) },
    outputSchema: {
      sides: z.number().int().min(2),
      value: z.number().int().min(1),
    },
    _meta: {
      "openai/toolInvocation/invoking": "Rolling…",
      "openai/toolInvocation/invoked": "Rolled.",
    },
  },
  async ({ sides }) => {
    const value = 1 + Math.floor(Math.random() * sides);
    return {
      structuredContent: { sides, value },
      content: [{ type: "text", text: `Rolled ${value} on ${sides} sides.` }],
    };
  }
);

// 2) Render tool: owns the template and requires data from roll_dice.
server.registerTool(
  "render_dice_widget",
  {
    title: "Render dice widget",
    description:
      "Render the dice widget from roll data. First call roll_dice, then pass its sides and value to this tool.",
    inputSchema: {
      sides: z.number().int().min(2),
      value: z.number().int().min(1),
    },
    outputSchema: {
      sides: z.number().int().min(2),
      value: z.number().int().min(1),
    },
    _meta: {
      ui: { resourceUri: TEMPLATE_URI },
      "openai/toolInvocation/invoking": "Rendering…",
      "openai/toolInvocation/invoked": "Rendered.",
    },
  },
  async ({ sides, value }) => ({
    structuredContent: { sides, value },
    content: [
      {
        type: "text",
        text: `Showing a ${sides}-sided roll: ${value}.`,
      },
    ],
  })
);

export default server;

Installiere esbuild zusammen mit den Serverabhängigkeiten. Speichere anschließend den folgenden Browsercode als dice-widget.ts im selben Verzeichnis wie die Serverdatei:

import { App } from "@modelcontextprotocol/ext-apps";

const container = document.createElement("div");
container.style.cssText = "font-family: system-ui; padding: 8px;";
const resultLine = document.createElement("div");
resultLine.style.cssText = "font-size: 20px; margin-bottom: 6px;";
const output = document.createElement("span");
output.id = "out";
output.textContent = "—";
resultLine.append("Result: ", output);
const rerollButton = document.createElement("button");
rerollButton.id = "reroll";
rerollButton.textContent = "Re-roll";
rerollButton.disabled = true;
container.append(resultLine, rerollButton);
document.body.append(container);

const app = new App({ name: "Dice widget", version: "1.0.0" });
let latestInput: Record<string, unknown> = {};
let latestOutput: Record<string, unknown> = {};

function render(result: Record<string, unknown>) {
  latestOutput = result;
  output.textContent = String(result.value ?? "—");
}

app.ontoolinput = ({ arguments: input }) => {
  latestInput = input ?? {};
};
app.ontoolresult = (result) => {
  render(result.structuredContent ?? {});
};

// Call the data tool without remounting the widget.
rerollButton.onclick = async () => {
  const candidate = latestOutput.sides ?? latestInput.sides;
  const sides =
    typeof candidate === "number" &&
    Number.isInteger(candidate) &&
    candidate >= 2
      ? candidate
      : 6;
  const next = await app.callServerTool({
    name: "roll_dice",
    arguments: { sides },
  });
  if (next.structuredContent) render(next.structuredContent);
};

await app.connect();
rerollButton.disabled = false;

Zustand verwalten

Eine von einem MCP-Server bereitgestellte UI arbeitet mit drei Arten von Zustand:

Zustandsart Zuständiges System Gültigkeitsdauer Beispiele
Geschäftsdaten (maßgeblich) MCP-Server oder externer Dienst Langfristig Aufgaben, Tickets, Dokumente
UI-Zustand (temporär) UI-Instanz Solange die UI-Instanz aktiv ist Ausgewählte Zeile, ausgeklappter Bereich, Sortierreihenfolge
Sitzungsübergreifender Zustand (dauerhaft) Von dir verwalteter Speicher Über Sitzungen und Unterhaltungen hinweg Gespeicherte Filter, Ansichtsmodus, Workspace

Speichere jeden Wert in dem System, das dafür zuständig ist. Die UI sollte die maßgeblichen Daten aus den Toolergebnissen anzeigen und den temporären Darstellungszustand darauf anwenden.

MCP server or external service
│
├── Authoritative business data
│
▼
UI
│
├── Ephemeral presentation state
│
└── Rendered view = business data + UI state

Geschäftsdaten auf dem Server halten

Für Geschäftsdaten ist der Stand auf dem Server maßgeblich. Speichere sie nie ausschließlich in der UI. Wenn jemand eine Aktion ausführt, läuft sie so ab:

  1. Die UI ruft ein MCP-Tool auf.
  2. Der Server prüft die Anfrage und aktualisiert die Daten.
  3. Der Server gibt den aktualisierten, maßgeblichen Datenstand zurück.
  4. Die UI zeigt diesen Datenstand an und behält den bisherigen Darstellungszustand bei, soweit er mit den neuen Daten vereinbar ist.

Gib ausreichend strukturierte Inhalte zurück, damit sowohl das Modell als auch die UI den neuen Zustand nachvollziehen können. So lässt sich die Unterhaltung auch dann sinnvoll fortsetzen, wenn die UI nicht geladen werden kann.

Temporären UI-Zustand in der UI halten

Verwalte Werte, die nur die Darstellung betreffen, mit der Zustandsverwaltung deines Frameworks. Beispiele sind ein ausgewähltes Element, ein geöffneter Bereich oder ein noch nicht angewendeter Filter. Jede gerenderte UI-Instanz hat ihren eigenen Zustand.

Wenn das Modell eine Auswahl oder eine vorbereitete Änderung kennen muss, sende diese Information über ui/update-model-context. So aktualisierst du mit MCP Apps den für das Modell sichtbaren Kontext auf allen kompatiblen Hosts.

In ChatGPT kannst du den Zustand optional für das jeweilige Widget speichern:

  • Lies den aktuellen Zustand aus window.openai.widgetState.
  • Speichere den neuen Zustand mit window.openai.setWidgetState(state).

setWidgetState arbeitet synchron. Rufe die Methode nach jeder relevanten Änderung des UI-Zustands auf. Du brauchst dafür kein await.

import { useState } from "react";

export function TaskList({
  tasks,
}: {
  tasks: { id: string; title: string }[];
}) {
  const [state, setState] = useState(
    window.openai?.widgetState ?? { selectedId: null }
  );

  function selectTask(selectedId: string) {
    const nextState = { ...state, selectedId };
    setState(nextState);
    window.openai?.setWidgetState?.(nextState);
  }

  return (
    <ul>
      {tasks.map((task) => (
        <li key={task.id}>
          <button
            type="button"
            aria-pressed={state.selectedId === task.id}
            onClick={() => selectTask(task.id)}
          >
            {task.title}
          </button>
        </li>
      ))}
    </ul>
  );
}

Der Widget-Zustand gehört zu genau einer gerenderten UI-Instanz. Verwende ihn weder als maßgebliche Quelle für Geschäftsdaten noch als dauerhaften Speicher.

Bilder für das Modell sichtbar machen

Wenn deine UI mit Bildern arbeitet, verwende für den Widget-Zustand die folgende Struktur:

  • modelContent: Inhalte im Text- oder JSON-Format, die das Modell sehen soll.
  • privateContent: Zustand, der ausschließlich für die UI bestimmt ist und für das Modell unsichtbar bleiben soll.
  • imageIds: Datei-IDs, die das Modell in späteren Gesprächsrunden erhalten soll.
const selectedFiles = await window.openai.selectFiles();

window.openai.setWidgetState({
  modelContent: "Review the currently selected images.",
  privateContent: {
    currentView: "image-viewer",
    filters: ["crop", "sharpen"],
  },
  imageIds: selectedFiles.map((file) => file.fileId),
});

Nimm nur IDs von Dateien auf, die mit window.openai.uploadFile hochgeladen, mit window.openai.selectFiles ausgewählt, über Dateiparameter eines Toolaufrufs empfangen oder als Dateiverweise in einem Toolergebnis zurückgegeben wurden.

Sitzungsübergreifenden Zustand auf deinem Server speichern

Nutze einen von dir verwalteten Speicher für Einstellungen und Daten, die über Unterhaltungen, Geräte oder Sitzungen hinweg erhalten bleiben müssen. Authentifiziere die Person, damit der MCP-Server jede Anfrage dem richtigen Konto zuordnen kann.

Beachte beim Einrichten eines dauerhaften Speichers folgende Punkte:

  • Halte die Latenz so gering, dass sich die UI flüssig bedienen lässt.
  • Schütze private Daten durch serverseitige Autorisierung.
  • Berücksichtige Anforderungen an Datenresidenz und Compliance.
  • Setze Ratenlimits für Anfragen aus Wiederholungsversuchen oder gleichzeitig aktiven UI-Instanzen.
  • Versioniere gespeicherte Objekte, damit du sie migrieren kannst und bestehende Unterhaltungen weiterhin funktionieren.

Vermeide localStorage für zentrale Zustandsdaten. Die UI läuft in einem isolierten iframe. Der Browserspeicher bietet keine verlässliche Grundlage für die geräte- oder sitzungsübergreifende Speicherung.

Grundgerüst für das Komponentenprojekt anlegen

Mit der Bridge von MCP Apps und den optionalen ChatGPT-Erweiterungen bist du jetzt vertraut. Als Nächstes legst du das Grundgerüst für dein Komponentenprojekt an.

Trenne den Komponentencode möglichst von der Serverlogik. Eine übliche Verzeichnisstruktur sieht so aus:

plugin-ui/
  server/            # MCP server (Python or Node)
  web/               # Component bundle source
    package.json
    tsconfig.json
    src/component.tsx
    dist/component.js   # Build output

Erstelle das Projekt und installiere die Abhängigkeiten. Empfohlen ist Node ab Version 18:

cd plugin-ui/web
npm init -y
npm install react@^19 react-dom@^19
npm install -D typescript esbuild

Wenn deine Komponente Bibliotheken für Drag-and-drop, Diagramme oder andere Funktionen benötigt, füge sie jetzt hinzu. Beschränke dich auf die benötigten Abhängigkeiten, damit das Bundle klein bleibt.

React-Komponente schreiben

Deine Einstiegsdatei sollte die Komponente in ein root-Element mounten. Die Komponente sollte ihre Ansicht aus dem neuesten Toolergebnis erzeugen, das sie über die Bridge von MCP Apps erhält (zum Beispiel über ui/notifications/tool-result).

Auf der Beispielseite findest du UI-Beispiele wie die Pizzaz-Liste mit Pizzerien.

Pizzaz-Komponentengalerie erkunden

Die UI-Beispiele enthalten Komponenten, die dir als Vorlage für deine eigene UI dienen können:

  • Pizzaz List: Nach Rang sortierte Kartenliste mit Favoriten und Schaltflächen für Aktionen.
    Screenshot der Listenkomponente von Pizzaz
  • Pizzaz Carousel: Horizontal scrollbares Karussell auf Basis von Embla für Layouts mit vielen Medieninhalten.
    Screenshot der Karussellkomponente von Pizzaz
  • Pizzaz Map: Mapbox-Integration mit Detailansicht im Vollbild und Synchronisierung mit dem Zustand des Hosts.
    Screenshot der Kartenkomponente von Pizzaz
  • Pizzaz Album: Galerie mit übereinander angeordneten Ansichten, in der sich ein einzelner Ort im Detail erkunden lässt.
    Screenshot der Albumkomponente von Pizzaz
  • Pizzaz Video: Skriptgesteuerter Videoplayer mit Einblendungen und Bedienelementen für den Vollbildmodus.

Jedes Beispiel zeigt, wie du Ressourcen bündelst, die APIs des Hosts anbindest und den Zustand für den Einsatz in Unterhaltungen strukturierst. Kopiere das Beispiel, das deinem Anwendungsfall am nächsten kommt, und passe die Datenschicht an die Antworten deiner Tools an.

Hilfs-Hooks für React

Mit diesem kleinen Hook kannst du ui/notifications/tool-result abonnieren:

import { useEffect, useState } from "react";

type ToolResult = { structuredContent?: unknown } | null;

export function useToolResult() {
  const [toolResult, setToolResult] = useState<ToolResult>(null);

  useEffect(() => {
    const onMessage = (event: MessageEvent) => {
      if (event.source !== window.parent) return;
      const message = event.data;
      if (!message || message.jsonrpc !== "2.0") return;
      if (message.method !== "ui/notifications/tool-result") return;
      setToolResult(message.params ?? null);
    };

    window.addEventListener("message", onMessage, { passive: true });
    return () => window.removeEventListener("message", onMessage);
  }, []);

  return toolResult;
}

Verwende toolResult?.structuredContent für die Darstellung und behandle die Daten als nicht vertrauenswürdige Eingabe.

Widgets lokalisieren

Der Host setzt document.documentElement.lang auf die Kennung des aktuellen Gebietsschemas. Verwende dieses Gebietsschema, um Übersetzungen zu laden und Datumsangaben und Zahlen zu formatieren. Führe npm install react-intl im Verzeichnis web/ aus, bevor du dieses Beispiel verwendest:

import { IntlProvider, FormattedMessage } from "react-intl";

const messages: Record<string, Record<string, string>> = {
  "en-US": { greeting: "Hello" },
  "es-ES": { greeting: "Hola" },
};

export function PluginUI() {
  const locale = document.documentElement.lang || "en-US";
  return (
    <IntlProvider
      locale={locale}
      messages={messages[locale] ?? messages["en-US"]}
    >
      <FormattedMessage id="greeting" defaultMessage="Hello" />
    </IntlProvider>
  );
}

Bundle für den iframe erstellen

Wenn deine React-Komponente fertig ist, kannst du sie zu einem einzigen JavaScript-Modul bündeln, das der Server direkt in das HTML einbetten kann:

// package.json
{
  "scripts": {
    "build": "esbuild src/component.tsx --bundle --format=esm --jsx=automatic --outfile=dist/component.js"
  }
}

Führe npm run build aus, um dist/component.js zu erzeugen. Wenn esbuild fehlende Abhängigkeiten meldet, prüfe, ob du npm install im Verzeichnis web/ ausgeführt hast. Prüfe auch, ob deine Importe den Namen der installierten Pakete entsprechen (zum Beispiel @react-dnd/html5-server-side oder react-dnd-html5-server-side).

Komponente in die Serverantwort einbetten

Stelle die Komponente als MCP-Ressource mit dem UI-MIME-Typ von MCP Apps bereit (text/html;profile=mcp-app). Wenn du @modelcontextprotocol/ext-apps/server verwendest, nutze vorzugsweise die Konstante RESOURCE_MIME_TYPE, statt die Zeichenfolge direkt anzugeben:

import {
  registerAppResource,
  RESOURCE_MIME_TYPE,
} from "@modelcontextprotocol/ext-apps/server";
import { readFileSync } from "node:fs";

const component = readFileSync("web/dist/component.js", "utf8");

registerAppResource(
  server,
  "project-board",
  "ui://project-board/v1.html",
  {},
  async () => ({
    contents: [
      {
        uri: "ui://project-board/v1.html",
        mimeType: RESOURCE_MIME_TYPE,
        text: `<div id="root"></div><script type="module">${component}</script>`,
        _meta: {
          ui: {
            prefersBorder: true,
            domain: "https://example.com",
            csp: {
              connectDomains: ["https://api.example.com"],
              resourceDomains: ["https://static.example.com"],
            },
          },
        },
      },
    ],
  })
);

Verknüpfe den Ressourcen-URI nur mit den Tools, die die Komponente rendern sollen. Verwende _meta.ui.resourceUri, damit die Komponente mit möglichst vielen Hosts für MCP Apps kompatibel ist. ChatGPT unterstützt außerdem _meta["openai/outputTemplate"] als Kompatibilitätsalias.

Behandle den Ressourcen-URI als Cache-Schlüssel. Wenn du HTML, JavaScript oder CSS so änderst, dass die neue Version nicht abwärtskompatibel ist, veröffentliche einen neuen URI und aktualisiere alle Tools, die auf die Ressource verweisen.

Content Security Policy (CSP)

Gib genau an, mit welchen Domains sich die Komponente verbindet und von welchen Domains sie Ressourcen lädt:

  • connectDomains für API-Anfragen.
  • resourceDomains für Skripte, Stylesheets, Bilder und andere Ressourcen.
  • frameDomains nur dann, wenn die Komponente iframes von bestimmten Origins einbetten muss.

Verschachtelte Frames sind standardmäßig gesperrt. Beschränke jede Freigabeliste auf die unbedingt erforderlichen Einträge. Bei der Prüfung des Plugins wird die deklarierte Richtlinie mit dem tatsächlichen Verhalten der UI abgeglichen.

Du kannst einen vorhandenen Editor oder eine Verwaltungsoberfläche einbetten, sofern die jeweilige Oberfläche zur selben registrierbaren Domain gehört wie dein MCP-Server. Ein Server unter https://api.example.com/mcp kann beispielsweise https://app.example.com in frameDomains angeben. Gib bei der Einreichung die erforderliche Begründung an und beachte die iframe-Richtlinie einschließlich der Einschränkungen für Shared Hosting und der Prüfanforderungen.

Für den Produktivbetrieb empfehlen sich UI-Vorlagen für Komponenten.

Während der Entwicklung kannst du das Komponenten-Bundle bei jeder Änderung am React-Code neu erstellen und den Server per Hot Reload aktualisieren.

Kaufabschluss in deiner UI anbieten

Wenn du den Kaufabschluss über die UI deines Plugins anbieten möchtest, zeige in der Komponente vor der Bestätigung die Produkte, Preise, Bedingungen und Zahlungsoptionen an. Gestalte die zugrunde liegenden Katalog- und Bestelltools so, dass sie auch ohne UI nutzbar sind. Wähle anschließend einen externen Checkout oder, sofern verfügbar, eine eingebettete Zahlungsoption.

Standardmäßig einen externen Checkout verwenden

Der externe Checkout ist die empfohlene und allgemein verfügbare Lösung. Verlinke aus der Komponente auf den Checkout, den du als Handelsunternehmen auf deiner eigenen Domain betreibst. Dort kümmerst du dich um:

  • Preisgestaltung und Zahlungsabwicklung.
  • Steuern, Rabatte und Gebühren.
  • Versand und Auftragsabwicklung.
  • Erstattungen, Support und die Einhaltung geltender Vorschriften.

Die aktuelle Genehmigung gilt nur für Plugins, über die sich physische Waren kaufen lassen. Biete andere Verkaufskategorien nur an, wenn OpenAI sie ausdrücklich für dein Plugin freigeschaltet hat.

Gespeicherte Zahlungsmethoden verwenden

Bei dafür zugelassenen Käufen physischer Waren kannst du optional eine UI anbieten, über die deine Kundschaft eine zuvor bei deinem Dienst gespeicherte Zahlungsmethode auswählt. In diesem Ablauf lassen sich zulässige gespeicherte Zahlungsmethoden anzeigen, aber keine neuen Zahlungsdaten erfassen. Dein MCP-Server verarbeitet den Kauf und gibt das maßgebliche Bestellergebnis zurück.

Zahlungsdialog von ChatGPT verwenden

Der eingebettete Checkout mit dem Zahlungsdialog von ChatGPT ist in einer privaten Betaphase für ausgewählte Marktplätze verfügbar. Sowohl bei der Entwicklung als auch bei der Nutzung hat nur ein eingeschränkter Personenkreis Zugriff.

Bei freigeschalteten Integrationen öffnet window.openai.requestCheckout den Zahlungsdialog von ChatGPT:

const order = await window.openai.requestCheckout(checkoutSession);

Der Checkout läuft in vier Schritten ab:

  1. Ein MCP-Tool gibt in structuredContent eine Checkout-Sitzung zurück.
  2. Die Komponente zeigt die Bestellpositionen, Gesamtbeträge, Bedingungen und Optionen für die Auftragsabwicklung an.
  3. Sobald sich die Person für die Zahlung entscheidet, ruft die Komponente requestCheckout(checkoutSession) auf.
  4. ChatGPT sendet das ausgewählte Zahlungstoken an das Tool complete_checkout des MCP-Servers. Das Tool belastet die Zahlungsmethode und gibt die abgeschlossene Bestellung zurück.

Die Checkout-Sitzung muss Folgendes enthalten:

  • Eine eindeutige Sitzungs-ID.
  • Bestellpositionen und Mengen.
  • Gesamtbeträge als Ganzzahlen in der kleinsten Einheit der jeweiligen Währung.
  • Metadaten zum Zahlungsanbieter und zum Handelsunternehmen.
  • Erforderliche Links zu rechtlichen Informationen, Datenschutz, Erstattungen und Support.

Für Preise und Bestellstatus ist der Server maßgeblich. Prüfe das Zahlungstoken, gestalte den Vorgang idempotent, speichere die Bestellung dauerhaft und gib einen Beleg auf Grundlage der maßgeblichen Bestelldaten zurück. Verlasse dich niemals auf Gesamtbeträge, die ausschließlich die Komponente berechnet hat.

Verwende payment_mode: "test", um den gesamten Ablauf ohne echte Zahlungen zu testen. Behandle Kaufabbrüche, abgelehnte Zahlungen und Fehler des Zahlungsanbieters in der Komponente.

Alle Felder der Checkout-Sitzung, das Verhalten der Zahlungsanbieter, die Ergebnisstruktur von complete_checkout und die Anforderungen an delegierte Zahlungen findest du in der Checkout-API-Referenz.