Tilføj en grænseflade med MCP Apps
På denne side
Lektionen er omskrevet den 3. november 2026 baseret på siden Add UI to your MCP server fra OpenAI Plugins-dokumentationen og koden til
@modelcontextprotocol/ext-apps1.7.5. Den tidligere lektion beskrev “widgets” (defineWidget) fra et ikke-eksisterende SDK; en grænseflade er en MCP Apps-ressource, der gengives af ChatGPT i en iframe. Kilder: Add UI to your MCP server · MCP Apps Specification.
Hvornår skal du tilføje en grænseflade
Grænsefladen er valgfri. Tilføj en, når brugeren har brug for at inspicere, sammenligne, ændre, bekræfte eller gennemse strukturerede oplysninger – og sørg for, at dine værktøjer stadig er nyttige uden den, så ChatGPT og Codex kan styre arbejdsgangen i klienter, der ikke viser en komponent.
MCP Apps-princippet
ChatGPT implementerer den åbne MCP Apps-standard. Serveren erklærer en grænsefladeressource, identificeret ved en ui://…-URI og leveret med MIME-typen text/html;profile=mcp-app; et værktøj knyttes til den via _meta.ui.resourceUri. Når dette værktøj kaldes, viser ChatGPT ressourcen i en iframe ved siden af samtalen. Komponenten kommunikerer med værten via JSON-RPC ved hjælp af postMessage:
| Besked | Rolle |
|---|---|
ui/initialize derefter ui/notifications/initialized | Åbn dialogen med værten |
ui/notifications/tool-input | Modtag værktøjskaldets argumenter |
ui/notifications/tool-result | Modtag værktøjsresultatet |
tools/call | Kald et serverværktøj fra grænsefladen |
ui/message | Send en opfølgende besked i samtalen |
ui/update-model-context | Informér modellen om et aktuelt valg eller en ændring |
På serversiden: Erklær ressourcen og værktøjet
Lad os genbesøge notes-serveren fra lektion 4. Pakken @modelcontextprotocol/ext-apps (i 1.x med SDK v1) tilbyder to hjælpefunktioner: registerAppResource, som anvender den korrekte MIME-type eksponeret af RESOURCE_MIME_TYPE-konstanten som standard, og registerAppTool, som kræver grænseflademetadatas.
import { readFileSync } from "node:fs";
import {
registerAppResource,
registerAppTool,
RESOURCE_MIME_TYPE,
} from "@modelcontextprotocol/ext-apps/server";
const URI_CARTE = "ui://widget/notes-v1.html"; // versioneret: dette er en cache-nøgle
const carteHtml = readFileSync("public/notes-widget.html", "utf8");
// Tilføj inde i creerServeur(), ved siden af list_notes og 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.` }],
})
);
Kun show_notes bærer grænsefladen. Dette er den afkobling, som OpenAI anbefaler: hvis hvert værktøj returnerede en skabelon, ville ChatGPT tegne iframen for ofte. Dataværktøjer (list_notes, add_note) søger, beregner eller modificerer og returnerer kun deres resultat; gengivelsesværktøjer modtager endelige data og returnerer skabelonen. Modellen kan dermed arbejde på dataene – filtrere, krydsreferere – før den beslutter at vise dem, og kortet vises kun én gang med en verificeret kontekst. Angiv afhængigheden i beskrivelsen af gengivelsesværktøjet, som vist ovenfor.
På iframe-siden: JSON-RPC-broen
Komponenten passer her ind i en enkelt HTML-fil uden byggetrin. Den åbner dialogen med værten og viser derefter hvert værktøjsresultat, den modtager.
<!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>
Det modtagne resultat er ikke-betroede data: vis det med textContent, aldrig ved at injicere det som HTML. Til en rigere grænseflade tilbyder den samme pakke en browserside App-klasse, der kapsler denne bro ind (modtager resultater, kalder værktøjer), som skal integreres i en bundle bygget med esbuild; OpenAI-eksempelrepositoryet viser komplette React-komponenter.
Valg af præsentation
Start med den indlejrede visning og anmod kun om mere plads, hvis arbejdsgangen kræver det:
| Præsentation | Anvendelse |
|---|---|
| Indlejret kort | Et målrettet resultat, en bekræftelse, nogle få handlinger uden dyb navigation |
| Indlejret karrusel | Gennemse og vælg blandt nogle få lignende, visuelle muligheder |
| Fuld skærm | En omfattende opgave: kort, redigeringslærred, detaljeret udforskning; ChatGPT-inputområdet forbliver tilgængeligt |
| Billede-i-billede | En igangværende aktivitet, der skal forblive synlig under samtalen: live-session, spil, video |
ChatGPT-specifikke udvidelser
Når MCP Apps-flowet er på plads, tilbyder ChatGPT udvidelser via window.openai, som kun skal bruges til det, som standarden ikke dækker. Foretræk standarden til almindelige behov; ChatGPT-aliasser forbliver tilgængelige for eksisterende integrationer:
| Behov | MCP Apps-standard | ChatGPT-alias |
|---|---|---|
| Knyt et værktøj til en grænseflade | _meta.ui.resourceUri | _meta["openai/outputTemplate"] |
| Modtag argumenter | ui/initialize + ui/notifications/tool-input | window.openai.toolInput |
| Modtag resultat | ui/notifications/tool-result | window.openai.toolOutput |
| Kald et værktøj | tools/call | window.openai.callTool |
| Send en opfølgende besked | ui/message | window.openai.sendFollowUpMessage |
Udvidelser uden en standardmodpart dækker integreret checkout (requestCheckout), filer (uploadFile, selectFiles, getFileDownloadUrl), værtstyrede modal-vinduer (requestModal) og vedvarende komponenttilstand (widgetState, setWidgetState). Registrér hver funktion, før du bruger den, med et fallback, hvor det er muligt – og test aldrig værtsnavnet, test funktionen:
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.";
}
Tre slags tilstand
| Tilstand | Ejer | Levetid | Eksempler |
|---|---|---|---|
| Forretningsdata, sandhedskilde | MCP-server eller ekstern tjeneste | Lang | Opgaver, tickets, dokumenter |
| Grænsefladetilstand, flygtig | Komponentinstans | Varigheden af dens visning | Valgt række, åben panel, sorteringsrækkefølge |
| Vedvarende tilstand på tværs af sessioner | Lager, du kontrollerer | Mellem samtaler og enheder | Gemte filtre, visningstilstand |
Forretningsdata forbliver på serveren: grænsefladen kalder et værktøj, serveren validerer og opdaterer, returnerer derefter referencetilstanden, som grænsefladen viser, mens den beholder det, der vedrører præsentation. Når modellen har brug for at kende et valg, sendes det via ui/update-model-context. window.openai.setWidgetState (synkron, ingen await) bevarer tilstanden for en instans, ikke forretningsdata. Vedvarende tilstand gemmes i dit lager bag autentificering; undgå localStorage, som hverken tilbyder kontinuitet mellem enheder eller pålidelighed i en isoleret iframe.
Content Security Policy
Komponenten erklærer i sine ressourcemetadata (_meta.ui.csp) de præcise domæner, den bruger: connectDomains til API-kald, resourceDomains til scripts, styles og billeder, frameDomains kun hvis den skal integrere specifikke iframes – nestede frames blokeres som standard. Hold disse lister så smalle som muligt: plugin-gennemgangen sammenligner den erklærede politik med grænsefladens faktiske adfærd. Og behandl ressource-URI’en som en cache-nøgle: for hver inkompatibel ændring i HTML, JavaScript eller CSS skal du publicere en ny URI og opdatere de værktøjer, der refererer til den.
To sidste detaljer: værten afspejler brugerens sprog i document.documentElement.lang, som skal bruges til at oversætte og formatere datoer og tal; og @openai/apps-sdk-ui-biblioteket tilbyder knapper, kort og felter, der matcher ChatGPT, hvis du ikke vil redesigne alt.
Vigtige pointer
- En grænseflade er en
ui://-ressource af typentext/html;profile=mcp-app, knyttet til et værktøj via_meta.ui.resourceUri - Komponenten kommunikerer med værten via JSON-RPC (
ui/initialize,tools/call,ui/notifications/tool-result…) - Adskil dataværktøjer og gengivelsesværktøjer: kun gengivelsesværktøjet bærer skabelonen
window.openaitilbyder kun udvidelser, som skal registreres før brug- Forretningsdata på serveren, snæver CSP, versioneret ressource-URI