Hoppa till huvudinnehåll
Svenska— Välj ett språk
Meny

Lägg till ett gränssnitt med MCP Apps

Lektion 6 av 14 Uppdaterad 3 november 2026 Utvecklare
På denna sida
  1. När du ska lägga till ett gränssnitt
  2. Principen för MCP Apps
  3. Serversidan: deklarera resursen och verktyget
  4. Iframe-sidan: JSON-RPC-bryggan
  5. Välja en presentation
  6. ChatGPT-specifika tillägg
  7. Tre typer av tillstånd
  8. Content Security Policy
  9. Viktiga punkter

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

MeddelandeRoll
ui/initialize sedan ui/notifications/initializedÖppna dialogen med värden
ui/notifications/tool-inputTa emot argument för verktygsanropet
ui/notifications/tool-resultTa emot verktygets resultat
tools/callAnropa ett serververktyg från gränssnittet
ui/messageSkicka ett uppföljningsmeddelande i konversationen
ui/update-model-contextInformera 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:

PresentationAnvändning
Inbäddat kortEtt målinriktat resultat, en bekräftelse, några åtgärder, utan djup navigering
Inbäddad karusellBläddra och välj bland några liknande, visuella alternativ
Hela skärmenEn rik uppgift: karta, redigeringscanvas, detaljerad utforskning; ChatGPT:s inmatningsområde förblir tillgängligt
Bild-i-bildEn 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:

BehovMCP Apps-standardChatGPT-alias
Koppla ett verktyg till ett gränssnitt_meta.ui.resourceUri_meta["openai/outputTemplate"]
Ta emot argumentui/initialize + ui/notifications/tool-inputwindow.openai.toolInput
Ta emot resultatui/notifications/tool-resultwindow.openai.toolOutput
Anropa ett verktygtools/callwindow.openai.callTool
Skicka ett uppföljningsmeddelandeui/messagewindow.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ÄgareLivslängdExempel
Affärsdata, sanningskällaMCP-server eller extern tjänstLångUppgifter, ärenden, dokument
Gränssnittstillstånd, flyktigtKomponentinstansUnder dess visningstidVald rad, öppen panel, sorteringsordning
Beständigt tillstånd över sessionerLagring du kontrollerarMellan konversationer och enheterSparade 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 typen text/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.openai tillhandahåller endast tillägg, att upptäckas innan användning
  • Affärsdata på servern, smal CSP, versionerad resurs-URI