Een interface toevoegen met MCP Apps
Op deze pagina
Les herschreven op 3 november 2026 op basis van de pagina Add UI to your MCP server uit de OpenAI Plugins-documentatie en de code voor
@modelcontextprotocol/ext-apps1.7.5. De vorige les beschreef “widgets” (defineWidget) van een niet-bestaande SDK; een interface is een MCP Apps-bron die door ChatGPT in een iframe wordt weergegeven. Bronnen: Add UI to your MCP server · MCP Apps Specification.
Wanneer u een interface toevoegt
De interface is optioneel. Voeg er een toe wanneer de gebruiker gestructureerde informatie moet inspecteren, vergelijken, wijzigen, bevestigen of doorbladeren. Zorg er echter voor dat uw tools ook zonder interface nuttig blijven, zodat ChatGPT en Codex de workflow kunnen aansturen in clients die geen component weergeven.
Het MCP Apps-principe
ChatGPT implementeert de open MCP Apps-standaard. De server declareert een interface-bron, geïdentificeerd door een ui://… URI en geserveerd met het MIME-type text/html;profile=mcp-app; een tool koppelt hieraan via _meta.ui.resourceUri. Wanneer deze tool wordt aangeroepen, toont ChatGPT de bron in een iframe, naast het gesprek. Het component communiceert met de host via JSON-RPC met behulp van postMessage:
| Bericht | Rol |
|---|---|
ui/initialize gevolgd door ui/notifications/initialized | De dialoog met de host openen |
ui/notifications/tool-input | De argumenten van de tool-aanroep ontvangen |
ui/notifications/tool-result | Het resultaat van de tool ontvangen |
tools/call | Een server-tool aanroepen vanuit de interface |
ui/message | Een vervolgbericht verzenden in het gesprek |
ui/update-model-context | Het model informeren over een huidige selectie of wijziging |
Serverzijde: declareer de bron en de tool
Laten we teruggrijpen naar de notities-server uit Les 4. Het pakket @modelcontextprotocol/ext-apps (in 1.x met SDK v1) biedt twee hulpmiddelen: registerAppResource, dat standaard het juiste MIME-type toepast dat wordt blootgesteld door de constante RESOURCE_MIME_TYPE, en registerAppTool, dat de interface-metadata vereist.
import { readFileSync } from "node:fs";
import {
registerAppResource,
registerAppTool,
RESOURCE_MIME_TYPE,
} from "@modelcontextprotocol/ext-apps/server";
const URI_CARTE = "ui://widget/notes-v1.html"; // met versie: dit is een cachesleutel
const carteHtml = readFileSync("public/notes-widget.html", "utf8");
// Toevoegen binnen creerServeur(), naast list_notes en add_note
registerAppResource(server, "notes-widget", URI_CARTE, {}, async () => ({
contents: [{ uri: URI_CARTE, mimeType: RESOURCE_MIME_TYPE, text: carteHtml }],
}));
registerAppTool(
server,
"show_notes",
{
title: "Show notes",
description:
"Displays notes in a card. To show only a subset, call list_notes first.",
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(s) displayed.` }],
})
);
Alleen show_notes bevat de interface. Dit is de ontkoppeling die OpenAI aanbeveelt: als elke tool een sjabloon zou retourneren, zou ChatGPT het iframe te vaak opnieuw tekenen. Gegevenstools (list_notes, add_note) zoeken, berekenen of wijzigen en retourneren alleen hun resultaat; weergavetools ontvangen definitieve gegevens en retourneren het sjabloon. Het model kan zo aan de gegevens werken—filteren, kruisverwijzen—voordat het besluit tot weergave, en de kaart verschijnt slechts één keer, met een geverifieerde context. Vermeld de afhankelijkheid in de beschrijving van de weergavetool, zoals hierboven getoond.
Iframe-zijde: de JSON-RPC-brug
Het component past hier in één enkel HTML-bestand, zonder bouwstap. Het opent de dialoog met de host en toont vervolgens elk tool-resultaat dat het ontvangt.
<!doctype html>
<html lang="en">
<head><meta charset="utf-8" /><title>Notes</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; // never innerHTML on received data
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>
Het ontvangen resultaat is niet-vertrouwde data: geef dit weer met textContent, nooit door het als HTML te injecteren. Voor een rijkere interface biedt hetzelfde pakket een browser-side App-klasse die deze brug kapselt (resultaten ontvangen, tools aanroepen), te integreren in een bundle gebouwd met esbuild; de OpenAI-voorbeeldenrepository toont complete React-componenten.
Een presentatievorm kiezen
Begin met de inline-weergave en vraag alleen om meer ruimte als de workflow dit vereist:
| Presentatie | Gebruik |
|---|---|
| Inline kaart | Een gericht resultaat, een bevestiging, een paar acties, zonder diepe navigatie |
| Inline carrousel | Bladeren en kiezen uit een paar vergelijkbare, visuele opties |
| Volledig scherm | Een rijke taak: kaart, bewerkingscanvas, gedetailleerde verkenning; het ChatGPT-invoergebied blijft beschikbaar |
| Picture-in-picture | Een lopende activiteit die zichtbaar moet blijven tijdens het gesprek: live sessie, spel, video |
ChatGPT-specifieke extensies
Zodra de MCP Apps-flow is ingesteld, biedt ChatGPT extensies via window.openai, die alleen gebruikt moeten worden voor wat de standaard niet dekt. Geef voor veelvoorkomende behoeften de voorkeur aan de standaard; ChatGPT-aliassen blijven beschikbaar voor bestaande integraties:
| Behoefte | MCP Apps Standaard | ChatGPT Alias |
|---|---|---|
| Een tool koppelen aan een interface | _meta.ui.resourceUri | _meta["openai/outputTemplate"] |
| Argumenten ontvangen | ui/initialize + ui/notifications/tool-input | window.openai.toolInput |
| Resultaat ontvangen | ui/notifications/tool-result | window.openai.toolOutput |
| Een tool aanroepen | tools/call | window.openai.callTool |
| Een vervolgbericht verzenden | ui/message | window.openai.sendFollowUpMessage |
Extensies zonder standaardequivalent omvatten geïntegreerde afrekenen (requestCheckout), bestanden (uploadFile, selectFiles, getFileDownloadUrl), door de host beheerde modale vensters (requestModal) en persistentie van componentstatus (widgetState, setWidgetState). Detecteer elke mogelijkheid voordat u deze gebruikt, met een fallback waar mogelijk—en test nooit de hostnaam, test de functie:
const openai = typeof window !== "undefined" ? window.openai : undefined;
if (openai?.requestModal) {
await openai.requestModal({ template: "ui://widget/details-v1.html" });
} else {
document.body.textContent = "This host does not support modal windows.";
}
Drie soorten status
| Status | Eigenaar | Levensduur | Voorbeelden |
|---|---|---|---|
| Bedrijfsgegevens, bron van waarheid | MCP-server of externe service | Lang | Taken, tickets, documenten |
| Interface-status, vluchtig | Component-instantie | Duur van de weergave | Geselecteerde rij, open paneel, sorteervolgorde |
| Duurzame status tussen sessies | Opslag die u beheert | Tussen gesprekken en apparaten | Opgeslagen filters, weergavemodus |
Bedrijfsgegevens blijven op de server: de interface roept een tool aan, de server valideert en werkt bij, en retourneert vervolgens de referentiestatus, die de interface weergeeft terwijl het presentatiegerelateerde aspecten behoudt. Wanneer het model een selectie moet kennen, verzendt u deze via ui/update-model-context. window.openai.setWidgetState (synchroon, geen await) behoudt de status van een instantie, geen bedrijfsgegevens. Duurzame status gaat naar uw opslag, achter authenticatie; vermijd localStorage, dat noch continuïteit tussen apparaten biedt, noch betrouwbaarheid in een geïsoleerd iframe.
Content Security Policy
Het component declareert in zijn resource-metadata (_meta.ui.csp) de exacte domeinen die het gebruikt: connectDomains voor API-aanroepen, resourceDomains voor scripts, stijlen en afbeeldingen, frameDomains alleen als het specifieke iframes moet integreren—geneste frames zijn standaard geblokkeerd. Houd deze lijsten zo smal mogelijk: de plug-in-review vergelijkt het gedeclareerde beleid met het feitelijke gedrag van de interface. En behandel de resource-URI als een cachesleutel: publiceer bij elke incompatibele wijziging in de HTML, JavaScript of CSS een nieuwe URI en werk de tools bij die ernaar verwijzen.
Twee laatste details: de host weerspiegelt de taal van de gebruiker in document.documentElement.lang, te gebruiken voor het vertalen en formatteren van datums en getallen; en de @openai/apps-sdk-ui-bibliotheek biedt knoppen, kaarten en velden die overeenkomen met ChatGPT als u niet alles opnieuw wilt ontwerpen.
Belangrijkste punten
- Een interface is een
ui://-bron van het typetext/html;profile=mcp-app, gekoppeld aan een tool via_meta.ui.resourceUri - Het component communiceert met de host via JSON-RPC (
ui/initialize,tools/call,ui/notifications/tool-result…) - Scheid gegevenstools en weergavetools: alleen de weergavetool bevat het sjabloon
window.openaibiedt alleen extensies, die gedetecteerd moeten worden voordat ze gebruikt worden- Bedrijfsgegevens op de server, smal CSP, resource-URI met versiebeheer