Aggiungi un'interfaccia con le app MCP
In questa pagina
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-apps1.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:
| Messaggio | Ruolo |
|---|---|
ui/initialize poi ui/notifications/initialized | Aprire il dialogo con l’host |
ui/notifications/tool-input | Ricevere gli argomenti della chiamata allo strumento |
ui/notifications/tool-result | Ricevere il risultato dello strumento |
tools/call | Chiamare uno strumento del server dall’interfaccia |
ui/message | Inviare un messaggio di follow-up nella conversazione |
ui/update-model-context | Informare 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:
| Presentazione | Utilizzo |
|---|---|
| Scheda inline | Un risultato mirato, una conferma, poche azioni, senza navigazione profonda |
| Carosello inline | Navigare e scegliere tra alcune opzioni visive simili |
| Schermo intero | Un compito ricco: mappa, tela di modifica, esplorazione dettagliata; l’area di input di ChatGPT rimane disponibile |
| Picture-in-picture | Un’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:
| Esigenza | Standard App MCP | Alias ChatGPT |
|---|---|---|
| Collegare uno strumento a un’interfaccia | _meta.ui.resourceUri | _meta["openai/outputTemplate"] |
| Ricevere argomenti | ui/initialize + ui/notifications/tool-input | window.openai.toolInput |
| Ricevere risultato | ui/notifications/tool-result | window.openai.toolOutput |
| Chiamare uno strumento | tools/call | window.openai.callTool |
| Inviare un messaggio di follow-up | ui/message | window.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
| Stato | Proprietario | Durata | Esempi |
|---|---|---|---|
| Dati aziendali, fonte di verità | Server MCP o servizio esterno | Lunga | Compiti, ticket, documenti |
| Stato dell’interfaccia, effimero | Istanza del componente | Durata della sua visualizzazione | Riga selezionata, pannello aperto, ordine di ordinamento |
| Stato durevole tra le sessioni | Archiviazione che controlli | Tra conversazioni e dispositivi | Filtri 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 tipotext/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.openaifornisce solo estensioni, da rilevare prima dell’uso- Dati aziendali sul server, CSP stretta, URI della risorsa versionato