Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

Een interface toevoegen met MCP Apps

Les 6 van 14 Bijgewerkt op 3 november 2026 Ontwikkelaar
Op deze pagina
  1. Wanneer u een interface toevoegt
  2. Het MCP Apps-principe
  3. Serverzijde: declareer de bron en de tool
  4. Iframe-zijde: de JSON-RPC-brug
  5. Een presentatievorm kiezen
  6. ChatGPT-specifieke extensies
  7. Drie soorten status
  8. Content Security Policy
  9. Belangrijkste punten

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

BerichtRol
ui/initialize gevolgd door ui/notifications/initializedDe dialoog met de host openen
ui/notifications/tool-inputDe argumenten van de tool-aanroep ontvangen
ui/notifications/tool-resultHet resultaat van de tool ontvangen
tools/callEen server-tool aanroepen vanuit de interface
ui/messageEen vervolgbericht verzenden in het gesprek
ui/update-model-contextHet 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:

PresentatieGebruik
Inline kaartEen gericht resultaat, een bevestiging, een paar acties, zonder diepe navigatie
Inline carrouselBladeren en kiezen uit een paar vergelijkbare, visuele opties
Volledig schermEen rijke taak: kaart, bewerkingscanvas, gedetailleerde verkenning; het ChatGPT-invoergebied blijft beschikbaar
Picture-in-pictureEen 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:

BehoefteMCP Apps StandaardChatGPT Alias
Een tool koppelen aan een interface_meta.ui.resourceUri_meta["openai/outputTemplate"]
Argumenten ontvangenui/initialize + ui/notifications/tool-inputwindow.openai.toolInput
Resultaat ontvangenui/notifications/tool-resultwindow.openai.toolOutput
Een tool aanroepentools/callwindow.openai.callTool
Een vervolgbericht verzendenui/messagewindow.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

StatusEigenaarLevensduurVoorbeelden
Bedrijfsgegevens, bron van waarheidMCP-server of externe serviceLangTaken, tickets, documenten
Interface-status, vluchtigComponent-instantieDuur van de weergaveGeselecteerde rij, open paneel, sorteervolgorde
Duurzame status tussen sessiesOpslag die u beheertTussen gesprekken en apparatenOpgeslagen 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 type text/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.openai biedt alleen extensies, die gedetecteerd moeten worden voordat ze gebruikt worden
  • Bedrijfsgegevens op de server, smal CSP, resource-URI met versiebeheer