Spring til hovedindhold
Dansk— Vælg et sprog
Menu

Tilføj en grænseflade med MCP Apps

Lektion 6 af 14 Opdateret 3. november 2026 Udvikler
På denne side
  1. Hvornår skal du tilføje en grænseflade
  2. MCP Apps-princippet
  3. På serversiden: Erklær ressourcen og værktøjet
  4. På iframe-siden: JSON-RPC-broen
  5. Valg af præsentation
  6. ChatGPT-specifikke udvidelser
  7. Tre slags tilstand
  8. Content Security Policy
  9. Vigtige pointer

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-apps 1.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:

BeskedRolle
ui/initialize derefter ui/notifications/initializedÅbn dialogen med værten
ui/notifications/tool-inputModtag værktøjskaldets argumenter
ui/notifications/tool-resultModtag værktøjsresultatet
tools/callKald et serverværktøj fra grænsefladen
ui/messageSend en opfølgende besked i samtalen
ui/update-model-contextInformé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æsentationAnvendelse
Indlejret kortEt målrettet resultat, en bekræftelse, nogle få handlinger uden dyb navigation
Indlejret karruselGennemse og vælg blandt nogle få lignende, visuelle muligheder
Fuld skærmEn omfattende opgave: kort, redigeringslærred, detaljeret udforskning; ChatGPT-inputområdet forbliver tilgængeligt
Billede-i-billedeEn 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:

BehovMCP Apps-standardChatGPT-alias
Knyt et værktøj til en grænseflade_meta.ui.resourceUri_meta["openai/outputTemplate"]
Modtag argumenterui/initialize + ui/notifications/tool-inputwindow.openai.toolInput
Modtag resultatui/notifications/tool-resultwindow.openai.toolOutput
Kald et værktøjtools/callwindow.openai.callTool
Send en opfølgende beskedui/messagewindow.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

TilstandEjerLevetidEksempler
Forretningsdata, sandhedskildeMCP-server eller ekstern tjenesteLangOpgaver, tickets, dokumenter
Grænsefladetilstand, flygtigKomponentinstansVarigheden af dens visningValgt række, åben panel, sorteringsrækkefølge
Vedvarende tilstand på tværs af sessionerLager, du kontrollererMellem samtaler og enhederGemte 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 typen text/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.openai tilbyder kun udvidelser, som skal registreres før brug
  • Forretningsdata på serveren, snæver CSP, versioneret ressource-URI