Lägg till ett gränssnitt med MCP Apps
På denna sida
Lektionen omskriven den 3 november 2026 baserat på sidan Add UI to your MCP server från OpenAI Plugins-dokumentationen och koden för
@modelcontextprotocol/ext-apps1.7.5. Den tidigare lektionen beskrev “widgets” (defineWidget) från ett icke-existerande SDK; ett gränssnitt är en MCP Apps-resurs som renderas av ChatGPT i en iframe. Källor: Add UI to your MCP server · MCP Apps Specification.
När du ska lägga till ett gränssnitt
Gränssnittet är valfritt. Lägg till ett när användaren behöver inspektera, jämföra, modifiera, bekräfta eller bläddra i strukturerad information – och se till att dina verktyg fortfarande är användbara utan det, så att ChatGPT och Codex kan driva arbetsflödet i klienter som inte visar en komponent.
Principen för MCP Apps
ChatGPT implementerar den öppna MCP Apps-standarden. Servern deklarerar en gränssnittsresurs, identifierad av en ui://…-URI och serverad med MIME-typen text/html;profile=mcp-app; ett verktyg kopplas till den via _meta.ui.resourceUri. När detta verktyg anropas visar ChatGPT resursen i en iframe, bredvid konversationen. Komponenten kommunicerar med värden via JSON-RPC med hjälp av postMessage:
| Meddelande | Roll |
|---|---|
ui/initialize sedan ui/notifications/initialized | Öppna dialogen med värden |
ui/notifications/tool-input | Ta emot argument för verktygsanropet |
ui/notifications/tool-result | Ta emot verktygets resultat |
tools/call | Anropa ett serververktyg från gränssnittet |
ui/message | Skicka ett uppföljningsmeddelande i konversationen |
ui/update-model-context | Informera modellen om ett aktuellt val eller en modifiering |
Serversidan: deklarera resursen och verktyget
Låt oss återvända till anteckningsservern från lektion 4. Paketet @modelcontextprotocol/ext-apps (i 1.x med SDK v1) tillhandahåller två hjälpfunktioner: registerAppResource, som applicerar korrekt MIME-typ som exponeras av konstanten RESOURCE_MIME_TYPE som standard, och registerAppTool, som kräver gränssnittsmetadata.
import { readFileSync } from "node:fs";
import {
registerAppResource,
registerAppTool,
RESOURCE_MIME_TYPE,
} from "@modelcontextprotocol/ext-apps/server";
const URI_CARTE = "ui://widget/notes-v1.html"; // versionerad: detta är en cache-nyckel
const carteHtml = readFileSync("public/notes-widget.html", "utf8");
// Lägg till inuti creerServeur(), bredvid list_notes och 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.` }],
})
);
Endast show_notes bär på gränssnittet. Detta är den avkoppling som OpenAI rekommenderar: om varje verktyg returnerade en mall skulle ChatGPT rita om iframen för ofta. Dataverktyg (list_notes, add_note) söker, beräknar eller modifierar och returnerar endast sitt resultat; renderingsverktyg tar emot slutgiltig data och returnerar mallen. Modellen kan således arbeta med datan – filtrera, korsreferera – innan den bestämmer sig för att visa, och kortet visas bara en gång, med en verifierad kontext. Indikera beroendet i renderingsverktygets beskrivning, som visas ovan.
Iframe-sidan: JSON-RPC-bryggan
Komponenten passar här i en enda HTML-fil, utan något byggsteg. Den öppnar dialogen med värden och visar sedan varje verktygsresultat den tar emot.
<!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 mottagna resultatet är ej betrodd data: visa den med textContent, aldrig genom att injicera den som HTML. För ett rikare gränssnitt tillhandahåller samma paket en App-klass på webbläsarsidan som kapslar in denna brygga (tar emot resultat, anropar verktyg), för att integreras i en bunt byggd med esbuild; OpenAI-exempelarkivet visar kompletta React-komponenter.
Välja en presentation
Börja med den inbäddade visningen och begär mer utrymme endast om arbetsflödet kräver det:
| Presentation | Användning |
|---|---|
| Inbäddat kort | Ett målinriktat resultat, en bekräftelse, några åtgärder, utan djup navigering |
| Inbäddad karusell | Bläddra och välj bland några liknande, visuella alternativ |
| Hela skärmen | En rik uppgift: karta, redigeringscanvas, detaljerad utforskning; ChatGPT:s inmatningsområde förblir tillgängligt |
| Bild-i-bild | En pågående aktivitet som måste förbli synlig under konversationen: live-session, spel, video |
ChatGPT-specifika tillägg
När MCP Apps-flödet är på plats erbjuder ChatGPT tillägg via window.openai, att användas endast för det som standarden inte täcker. För vanliga behov, föredra standarden; ChatGPT-alias finns kvar för befintliga integrationer:
| Behov | MCP Apps-standard | ChatGPT-alias |
|---|---|---|
| Koppla ett verktyg till ett gränssnitt | _meta.ui.resourceUri | _meta["openai/outputTemplate"] |
| Ta emot argument | ui/initialize + ui/notifications/tool-input | window.openai.toolInput |
| Ta emot resultat | ui/notifications/tool-result | window.openai.toolOutput |
| Anropa ett verktyg | tools/call | window.openai.callTool |
| Skicka ett uppföljningsmeddelande | ui/message | window.openai.sendFollowUpMessage |
Tillägg utan motsvarighet i standarden täcker integrerad utcheckning (requestCheckout), filer (uploadFile, selectFiles, getFileDownloadUrl), värdhanterade modalfönster (requestModal) och komponenttillståndspersistens (widgetState, setWidgetState). Upptäck varje funktion innan du använder den, med en reservlösning när möjligt – och testa aldrig värdnamnet, testa 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 typer av tillstånd
| Tillstånd | Ägare | Livslängd | Exempel |
|---|---|---|---|
| Affärsdata, sanningskälla | MCP-server eller extern tjänst | Lång | Uppgifter, ärenden, dokument |
| Gränssnittstillstånd, flyktigt | Komponentinstans | Under dess visningstid | Vald rad, öppen panel, sorteringsordning |
| Beständigt tillstånd över sessioner | Lagring du kontrollerar | Mellan konversationer och enheter | Sparade filter, visningsläge |
Affärsdata stannar på servern: gränssnittet anropar ett verktyg, servern validerar och uppdaterar, returnerar sedan referenstillståndet, vilket gränssnittet visar medan det behåller det som rör presentationen. När modellen behöver känna till ett val, skicka det via ui/update-model-context. window.openai.setWidgetState (synkront, inget await) bevarar tillståndet för en instans, inte affärsdata. Beständigt tillstånd hamnar i din lagring, bakom autentisering; undvik localStorage, som varken erbjuder kontinuitet mellan enheter eller tillförlitlighet i en isolerad iframe.
Content Security Policy
Komponenten deklarerar, i sina resursmetadata (_meta.ui.csp), de exakta domäner den använder: connectDomains för API-anrop, resourceDomains för skript, stilar och bilder, frameDomains endast om den måste integrera specifika iframes – nästlade ramar blockeras som standard. Håll dessa listor så smala som möjligt: plugin-granskningen jämför den deklarerade policyn med gränssnittets faktiska beteende. Och behandla resurs-URI:n som en cache-nyckel: för varje inkompatibel ändring av HTML, JavaScript eller CSS, publicera en ny URI och uppdatera verktygen som refererar till den.
Två sista detaljer: värden speglar användarens språk i document.documentElement.lang, att användas för att översätta och formatera datum och tal; och biblioteket @openai/apps-sdk-ui tillhandahåller knappar, kort och fält som matchar ChatGPT om du inte vill designa om allt.
Viktiga punkter
- Ett gränssnitt är en
ui://-resurs av typentext/html;profile=mcp-app, kopplad till ett verktyg via_meta.ui.resourceUri - Komponenten kommunicerar med värden via JSON-RPC (
ui/initialize,tools/call,ui/notifications/tool-result…) - Separera dataverktyg och renderingsverktyg: endast renderingsverktyget bär på mallen
window.openaitillhandahåller endast tillägg, att upptäckas innan användning- Affärsdata på servern, smal CSP, versionerad resurs-URI