Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Aggiungi un'interfaccia con le app MCP

Lezione 6 di 14 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Quando aggiungere un’interfaccia
  2. Il principio delle App MCP
  3. Lato server: dichiara la risorsa e lo strumento
  4. Lato iframe: il ponte JSON-RPC
  5. Scegliere una presentazione
  6. Estensioni specifiche di ChatGPT
  7. Tre tipi di stato
  8. Content Security Policy
  9. Punti chiave

Lezione riscritta il 3 novembre 2026 basata sulla pagina Add UI to your MCP server della documentazione dei Plugin OpenAI e sul codice di @modelcontextprotocol/ext-apps 1.7.5. La lezione precedente descriveva i “widget” (defineWidget) di un SDK inesistente; un’interfaccia è una risorsa delle App MCP renderizzata da ChatGPT in un iframe. Fonti: Add UI to your MCP server · MCP Apps Specification.

Quando aggiungere un’interfaccia

L’interfaccia è opzionale. Aggiungila quando l’utente deve ispezionare, confrontare, modificare, confermare o navigare informazioni strutturate, mantenendo però i tuoi strumenti utili anche senza di essa, così che ChatGPT e Codex possano guidare il flusso di lavoro nei client che non visualizzano un componente.

Il principio delle App MCP

ChatGPT implementa lo standard aperto delle App MCP. Il server dichiara una risorsa di interfaccia, identificata da un URI ui://… e servita con il tipo MIME text/html;profile=mcp-app; uno strumento vi si collega tramite _meta.ui.resourceUri. Quando questo strumento viene chiamato, ChatGPT visualizza la risorsa in un iframe, accanto alla conversazione. Il componente comunica con l’host tramite JSON-RPC utilizzando postMessage:

MessaggioRuolo
ui/initialize poi ui/notifications/initializedAprire il dialogo con l’host
ui/notifications/tool-inputRicevere gli argomenti della chiamata allo strumento
ui/notifications/tool-resultRicevere il risultato dello strumento
tools/callChiamare uno strumento del server dall’interfaccia
ui/messageInviare un messaggio di follow-up nella conversazione
ui/update-model-contextInformare il modello di una selezione o modifica corrente

Lato server: dichiara la risorsa e lo strumento

Rivediamo il server di note della Lezione 4. Il pacchetto @modelcontextprotocol/ext-apps (nella versione 1.x con SDK v1) fornisce due helper: registerAppResource, che applica il tipo MIME corretto esposto dalla costante RESOURCE_MIME_TYPE per impostazione predefinita, e registerAppTool, che richiede i metadati dell’interfaccia.

import { readFileSync } from "node:fs";
import {
  registerAppResource,
  registerAppTool,
  RESOURCE_MIME_TYPE,
} from "@modelcontextprotocol/ext-apps/server";

const URI_CARTE = "ui://widget/notes-v1.html"; // versionato: questa è una chiave di cache
const carteHtml = readFileSync("public/notes-widget.html", "utf8");

// Aggiungi all'interno di creerServeur(), accanto a list_notes e add_note
registerAppResource(server, "notes-widget", URI_CARTE, {}, async () => ({
  contents: [{ uri: URI_CARTE, mimeType: RESOURCE_MIME_TYPE, text: carteHtml }],
}));

registerAppTool(
  server,
  "show_notes",
  {
    title: "Mostra note",
    description:
      "Visualizza le note in una scheda. Per mostrare solo un sottoinsieme, chiama prima list_notes.",
    inputSchema: {},
    outputSchema: schemaNotes,
    annotations: { readOnlyHint: true, openWorldHint: false, destructiveHint: false },
    _meta: { ui: { resourceUri: URI_CARTE } },
  },
  async () => ({
    structuredContent: { notes },
    content: [{ type: "text", text: `${notes.length} nota(e) visualizzata(e).` }],
  })
);

Solo show_notes trasporta l’interfaccia. Questo è il disaccoppiamento raccomandato da OpenAI: se ogni strumento restituisse un template, ChatGPT ridisegnerebbe l’iframe troppo spesso. Gli strumenti dati (list_notes, add_note) cercano, calcolano o modificano e restituiscono solo il loro risultato; gli strumenti di rendering ricevono dati finali e restituiscono il template. Il modello può così lavorare sui dati—filtrare, incrociare—prima di decidere di visualizzare, e la scheda appare una sola volta, con un contesto verificato. Indica la dipendenza nella descrizione dello strumento di rendering, come mostrato sopra.

Lato iframe: il ponte JSON-RPC

Il componente sta qui in un singolo file HTML, senza passaggi di build. Apre il dialogo con l’host, poi visualizza ogni risultato dello strumento che riceve.

<!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; // mai innerHTML su dati ricevuti
            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>

Il risultato ricevuto è dato non attendibile: visualizzalo con textContent, mai iniettandolo come HTML. Per un’interfaccia più ricca, lo stesso pacchetto fornisce una classe App lato browser che incapsula questo ponte (ricezione risultati, chiamata strumenti), da integrare in un bundle costruito con esbuild; il repository degli esempi OpenAI mostra componenti React completi.

Scegliere una presentazione

Inizia con la visualizzazione inline e richiedi più spazio solo se il flusso di lavoro lo richiede:

PresentazioneUtilizzo
Scheda inlineUn risultato mirato, una conferma, poche azioni, senza navigazione profonda
Carosello inlineNavigare e scegliere tra alcune opzioni visive simili
Schermo interoUn compito ricco: mappa, tela di modifica, esplorazione dettagliata; l’area di input di ChatGPT rimane disponibile
Picture-in-pictureUn’attività in corso che deve rimanere visibile durante la conversazione: sessione live, gioco, video

Estensioni specifiche di ChatGPT

Una volta stabilito il flusso delle App MCP, ChatGPT offre estensioni tramite window.openai, da usare solo per ciò che lo standard non copre. Per le esigenze comuni, preferisci lo standard; gli alias di ChatGPT rimangono disponibili per le integrazioni esistenti:

EsigenzaStandard App MCPAlias ChatGPT
Collegare uno strumento a un’interfaccia_meta.ui.resourceUri_meta["openai/outputTemplate"]
Ricevere argomentiui/initialize + ui/notifications/tool-inputwindow.openai.toolInput
Ricevere risultatoui/notifications/tool-resultwindow.openai.toolOutput
Chiamare uno strumentotools/callwindow.openai.callTool
Inviare un messaggio di follow-upui/messagewindow.openai.sendFollowUpMessage

Le estensioni senza un equivalente standard coprono il checkout integrato (requestCheckout), i file (uploadFile, selectFiles, getFileDownloadUrl), le finestre modali gestite dall’host (requestModal) e la persistenza dello stato del componente (widgetState, setWidgetState). Rileva ogni capacità prima di usarla, con un fallback quando possibile, e non testare mai il nome dell’host, testa la funzione:

const openai = typeof window !== "undefined" ? window.openai : undefined;
if (openai?.requestModal) {
  await openai.requestModal({ template: "ui://widget/details-v1.html" });
} else {
  document.body.textContent = "Questo host non supporta le finestre modali.";
}

Tre tipi di stato

StatoProprietarioDurataEsempi
Dati aziendali, fonte di veritàServer MCP o servizio esternoLungaCompiti, ticket, documenti
Stato dell’interfaccia, effimeroIstanza del componenteDurata della sua visualizzazioneRiga selezionata, pannello aperto, ordine di ordinamento
Stato durevole tra le sessioniArchiviazione che controlliTra conversazioni e dispositiviFiltri salvati, modalità di visualizzazione

I dati aziendali restano sul server: l’interfaccia chiama uno strumento, il server valida e aggiorna, poi restituisce lo stato di riferimento, che l’interfaccia visualizza mantenendo ciò che riguarda la presentazione. Quando il modello deve conoscere una selezione, inviala tramite ui/update-model-context. window.openai.setWidgetState (sincrono, nessun await) preserva lo stato di un’istanza, non i dati aziendali. Lo stato durevole va nella tua archiviazione, dietro autenticazione; evita localStorage, che non offre né continuità tra dispositivi né affidabilità in un iframe isolato.

Content Security Policy

Il componente dichiara, nei suoi metadati di risorsa (_meta.ui.csp), i domini esatti che utilizza: connectDomains per le chiamate API, resourceDomains per script, stili e immagini, frameDomains solo se deve integrare iframe specifici—i frame annidati sono bloccati per impostazione predefinita. Mantieni questi elenchi il più stretti possibile: la revisione del plugin confronta la politica dichiarata con il comportamento effettivo dell’interfaccia. E tratta l’URI della risorsa come una chiave di cache: per ogni modifica incompatibile all’HTML, JavaScript o CSS, pubblica un nuovo URI e aggiorna gli strumenti che vi fanno riferimento.

Due ultimi dettagli: l’host riflette la lingua dell’utente in document.documentElement.lang, da usare per tradurre e formattare date e numeri; e la libreria @openai/apps-sdk-ui fornisce pulsanti, schede e campi corrispondenti a ChatGPT se non vuoi ridisegnare tutto.

Punti chiave

  • Un’interfaccia è una risorsa ui:// di tipo text/html;profile=mcp-app, collegata a uno strumento tramite _meta.ui.resourceUri
  • Il componente comunica con l’host tramite JSON-RPC (ui/initialize, tools/call, ui/notifications/tool-result…)
  • Separa gli strumenti dati dagli strumenti di rendering: solo lo strumento di rendering trasporta il template
  • window.openai fornisce solo estensioni, da rilevare prima dell’uso
  • Dati aziendali sul server, CSP stretta, URI della risorsa versionato