Eine Schnittstelle mit MCP-Apps hinzufügen
Auf dieser Seite
Lektion am 3. November 2026 neu geschrieben basierend auf der Seite Add UI to your MCP server aus der OpenAI Plugins-Dokumentation und dem Code für
@modelcontextprotocol/ext-apps1.7.5. Die vorherige Lektion beschrieb „Widgets” (defineWidget) aus einem nicht existierenden SDK; eine Schnittstelle ist eine MCP-Apps-Ressource, die von ChatGPT in einem iframe dargestellt wird. Quellen: Add UI to your MCP server · MCP Apps Specification.
Wann Sie eine Schnittstelle hinzufügen
Die Schnittstelle ist optional. Fügen Sie eine hinzu, wenn der Benutzer strukturierte Informationen inspizieren, vergleichen, ändern, bestätigen oder durchsuchen muss – und halten Sie Ihre Werkzeuge auch ohne sie nützlich, damit ChatGPT und Codex den Arbeitsablauf in Clients steuern können, die kein Komponente anzeigen.
Das MCP-Apps-Prinzip
ChatGPT implementiert den offenen MCP-Apps-Standard. Der Server deklariert eine Schnittstellenressource, die durch eine ui://… URI identifiziert wird und mit dem MIME-Typ text/html;profile=mcp-app bereitgestellt wird; ein Werkzeug verbindet sich mit ihr über _meta.ui.resourceUri. Wenn dieses Werkzeug aufgerufen wird, zeigt ChatGPT die Ressource in einem iframe neben dem Gespräch an. Die Komponente kommuniziert mit dem Host über JSON-RPC mittels postMessage:
| Nachricht | Rolle |
|---|---|
ui/initialize dann ui/notifications/initialized | Das Gespräch mit dem Host eröffnen |
ui/notifications/tool-input | Die Argumente des Werkzeugaufrufs empfangen |
ui/notifications/tool-result | Das Werkzeugergebnis empfangen |
tools/call | Ein Server-Werkzeug von der Schnittstelle aus aufrufen |
ui/message | Eine Nachfolgenachrichtigung im Gespräch senden |
ui/update-model-context | Das Modell über eine aktuelle Auswahl oder Änderung informieren |
Serverseite: Ressource und Werkzeug deklarieren
Lassen Sie uns die Notizen-Server-Notizen aus Lektion 4 erneut betrachten. Das Paket @modelcontextprotocol/ext-apps (in 1.x mit SDK v1) bietet zwei Helfer: registerAppResource, der den korrekten MIME-Typ anwendet, der standardmäßig durch die Konstante RESOURCE_MIME_TYPE exponiert wird, und registerAppTool, der die Schnittstellenmetadaten erfordert.
import { readFileSync } from "node:fs";
import {
registerAppResource,
registerAppTool,
RESOURCE_MIME_TYPE,
} from "@modelcontextprotocol/ext-apps/server";
const URI_CARTE = "ui://widget/notes-v1.html"; // versioniert: dies ist ein Cache-Schlüssel
const carteHtml = readFileSync("public/notes-widget.html", "utf8");
// Fügen Sie dies in creerServeur() hinzu, neben list_notes und add_note
registerAppResource(server, "notes-widget", URI_CARTE, {}, async () => ({
contents: [{ uri: URI_CARTE, mimeType: RESOURCE_MIME_TYPE, text: carteHtml }],
}));
registerAppTool(
server,
"show_notes",
{
title: "Notizen anzeigen",
description:
"Zeigt Notizen in einer Karte an. Um nur einen Teil anzuzeigen, rufen Sie zuerst list_notes auf.",
inputSchema: {},
outputSchema: schemaNotes,
annotations: { readOnlyHint: true, openWorldHint: false, destructiveHint: false },
_meta: { ui: { resourceUri: URI_CARTE } },
},
async () => ({
structuredContent: { notes },
content: [{ type: "text", text: `${notes.length} Note(n) angezeigt.` }],
})
);
Nur show_notes trägt die Schnittstelle. Dies ist die Entkopplung, die OpenAI empfiehlt: Wenn jedes Werkzeug ein Template zurückgeben würde, würde ChatGPT das iframe zu oft neu zeichnen. Datenwerkzeuge (list_notes, add_note) suchen, berechnen oder ändern und geben nur ihr Ergebnis zurück; Renderwerkzeuge erhalten finale Daten und geben das Template zurück. Das Modell kann also mit den Daten arbeiten – filtern, verknüpfen –, bevor es entscheidet, anzuzeigen, und die Karte erscheint nur einmal, mit einem verifizierten Kontext. Geben Sie die Abhängigkeit in der Beschreibung des Renderwerkzeugs an, wie oben gezeigt.
Iframe-Seite: Die JSON-RPC-Brücke
Die Komponente passt hier in eine einzelne HTML-Datei, ohne Build-Schritt. Sie eröffnet das Gespräch mit dem Host und zeigt dann jedes Werkzeugergebnis an, das sie empfängt.
<!doctype html>
<html lang="en">
<head><meta charset="utf-8" /><title>Notizen</title></head>
<body>
<ul id="liste"></ul>
<script type="module">
const liste = document.querySelector("#liste");
const enAttente = new Map();
let dernierId = 0;
const envoyer = (message) =>
window.parent.postMessage({ jsonrpc: "2.0", ...message }, "*");
const requete = (method, params) =>
new Promise((resolve, reject) => {
const id = ++dernierId;
enAttente.set(id, { resolve, reject });
envoyer({ id, method, params });
});
const afficher = (resultat) => {
const notes = resultat?.structuredContent?.notes ?? [];
liste.replaceChildren(
...notes.map((note) => {
const li = document.createElement("li");
li.textContent = note.text; // niemals innerHTML auf empfangene Daten
return li;
})
);
};
window.addEventListener("message", (event) => {
if (event.source !== window.parent) return;
const msg = event.data;
if (msg?.jsonrpc !== "2.0") return;
if (typeof msg.id === "number" && enAttente.has(msg.id)) {
const { resolve, reject } = enAttente.get(msg.id);
enAttente.delete(msg.id);
msg.error ? reject(msg.error) : resolve(msg.result);
} else if (msg.method === "ui/notifications/tool-result") {
afficher(msg.params);
}
});
await requete("ui/initialize", {
appInfo: { name: "notes-widget", version: "0.1.0" },
appCapabilities: {},
protocolVersion: "2026-01-26",
});
envoyer({ method: "ui/notifications/initialized", params: {} });
</script>
</body>
</html>
Das empfangene Ergebnis sind un vertrauenswürdige Daten: Zeigen Sie es mit textContent an, niemals durch Einsetzen als HTML. Für eine reichhaltigere Schnittstelle bietet dasselbe Paket eine browserseitige App-Klasse, die diese Brücke kapselt (Ergebnisse empfangen, Werkzeuge aufrufen), um in ein Bündel integriert zu werden, das mit esbuild erstellt wird; das OpenAI-Beispieldepot zeigt vollständige React-Komponenten.
Eine Darstellung wählen
Beginnen Sie mit der Inline-Anzeige und fordern Sie mehr Platz nur an, wenn der Arbeitsablauf dies erfordert:
| Darstellung | Verwendung |
|---|---|
| Inline-Karte | Ein gezieltes Ergebnis, eine Bestätigung, einige Aktionen, ohne tiefe Navigation |
| Inline-Karussell | Durchsuchen und unter wenigen ähnlichen, visuellen Optionen wählen |
| Vollbild | Eine reiche Aufgabe: Karte, Bearbeitungsfläche, detaillierte Erkundung; der ChatGPT-Eingabebereich bleibt verfügbar |
| Bild-in-Bild | Eine laufende Aktivität, die während des Gesprächs sichtbar bleiben muss: Live-Sitzung, Spiel, Video |
ChatGPT-spezifische Erweiterungen
Sobald der MCP-Apps-Workflow eingerichtet ist, bietet ChatGPT Erweiterungen über window.openai an, die nur für verwendet werden sollen, was der Standard nicht abdeckt. Für gängige Bedürfnisse bevorzugen Sie den Standard; ChatGPT-Aliase bleiben für bestehende Integrationen verfügbar:
| Bedarf | MCP-Apps-Standard | ChatGPT-Alias |
|---|---|---|
| Ein Werkzeug an eine Schnittstelle anbinden | _meta.ui.resourceUri | _meta["openai/outputTemplate"] |
| Argumente empfangen | ui/initialize + ui/notifications/tool-input | window.openai.toolInput |
| Ergebnis empfangen | ui/notifications/tool-result | window.openai.toolOutput |
| Werkzeug aufrufen | tools/call | window.openai.callTool |
| Nachfolgenachrichtigung senden | ui/message | window.openai.sendFollowUpMessage |
Erweiterungen ohne Standardäquivalent decken integrierte Kassenabwicklung (requestCheckout), Dateien (uploadFile, selectFiles, getFileDownloadUrl) und vom Host verwaltete Modal-Fenster (requestModal) sowie die Persistenz des Komponentenzustands (widgetState, setWidgetState) ab. Erkennen Sie jede Fähigkeit vor der Verwendung, mit einem Fallback, wenn möglich – und testen Sie niemals den Hostnamen, testen Sie die Funktion:
const openai = typeof window !== "undefined" ? window.openai : undefined;
if (openai?.requestModal) {
await openai.requestModal({ template: "ui://widget/details-v1.html" });
} else {
document.body.textContent = "Dieser Host unterstützt keine Modal-Fenster.";
}
Drei Arten von Zuständen
| Zustand | Eigentümer | Lebensdauer | Beispiele |
|---|---|---|---|
| Geschäftsdaten, Quelle der Wahrheit | MCP-Server oder externer Dienst | Lang | Aufgaben, Tickets, Dokumente |
| Schnittstellenzustand, vorübergehend | Komponenteninstanz | Dauer ihrer Anzeige | Ausgewählte Zeile, offenes Panel, Sortierreihenfolge |
| Dauerhafter Zustand über Sitzungen hinweg | Speicher, den Sie kontrollieren | Zwischen Gesprächen und Geräten | Gespeicherte Filter, Anzeigemodus |
Geschäftsdaten bleiben auf dem Server: Die Schnittstelle ruft ein Werkzeug auf, der Server validiert und aktualisiert, und gibt dann den Referenzzustand zurück, den die Schnittstelle anzeigt, während sie behält, was sich auf die Darstellung bezieht. Wenn das Modell eine Auswahl wissen muss, senden Sie sie über ui/update-model-context. window.openai.setWidgetState (synchron, kein await) bewahrt den Zustand einer Instanz, nicht die Geschäftsdaten. Dauerhafter Zustand geht in Ihren Speicher, hinter Authentifizierung; vermeiden Sie localStorage, das weder Kontinuität zwischen Geräten noch Zuverlässigkeit in einem isolierten iframe bietet.
Content Security Policy
Die Komponente deklariert in ihren Ressourcendaten (_meta.ui.csp) die genauen Domänen, die sie verwendet: connectDomains für API-Aufrufe, resourceDomains für Skripte, Styles und Bilder, frameDomains nur, wenn sie bestimmte iframes integrieren muss – verschachtelte Rahmen sind standardmäßig blockiert. Halten Sie diese Listen so eng wie möglich: Die Plugin-Prüfung vergleicht die deklarierte Richtlinie mit dem tatsächlichen Verhalten der Schnittstelle. Und behandeln Sie die Ressourcen-URI als Cache-Schlüssel: Für jede inkompatible Änderung an HTML, JavaScript oder CSS veröffentlichen Sie eine neue URI und aktualisieren Sie die Werkzeuge, die darauf verweisen.
Zwei letzte Details: Der Host spiegelt die Sprache des Benutzers in document.documentElement.lang wider, um für das Übersetzen und Formatieren von Daten und Zahlen verwendet zu werden; und die Bibliothek @openai/apps-sdk-ui bietet Buttons, Karten und Felder, die ChatGPT entsprechen, wenn Sie nicht alles neu gestalten möchten.
Kernaussagen
- Eine Schnittstelle ist eine
ui://-Ressource vom Typtext/html;profile=mcp-app, die über_meta.ui.resourceUrian ein Werkzeug angehängt ist - Die Komponente kommuniziert mit dem Host über JSON-RPC (
ui/initialize,tools/call,ui/notifications/tool-result…) - Trennen Sie Datenwerkzeuge und Renderwerkzeuge: Nur das Renderwerkzeug trägt das Template
window.openaibietet nur Erweiterungen, die vor der Verwendung erkannt werden müssen- Geschäftsdaten auf dem Server, enge CSP, versionierte Ressourcen-URI