Añadir una interfaz con aplicaciones MCP
En esta página
Lección reescrita el 3 de noviembre de 2026 basándose en la página Add UI to your MCP server de la documentación de Plugins de OpenAI y en el código de
@modelcontextprotocol/ext-apps1.7.5. La lección anterior describía «widgets» (defineWidget) de un SDK inexistente; una interfaz es un recurso de aplicaciones MCP que ChatGPT renderiza en un iframe. Fuentes: Add UI to your MCP server · Especificación de aplicaciones MCP.
Cuándo añadir una interfaz
La interfaz es opcional. Añade una cuando el usuario necesite inspeccionar, comparar, modificar, confirmar o navegar por información estructurada, y mantén tus herramientas útiles sin ella, de modo que ChatGPT y Codex puedan dirigir el flujo de trabajo en clientes que no muestren un componente.
El principio de las aplicaciones MCP
ChatGPT implementa el estándar abierto de aplicaciones MCP. El servidor declara un recurso de interfaz, identificado por un URI ui://… y servido con el tipo MIME text/html;profile=mcp-app; una herramienta se adjunta a él mediante _meta.ui.resourceUri. Cuando se llama a esta herramienta, ChatGPT muestra el recurso en un iframe, junto a la conversación. El componente se comunica con el anfitrión mediante JSON-RPC usando postMessage:
| Mensaje | Función |
|---|---|
ui/initialize y luego ui/notifications/initialized | Abrir el diálogo con el anfitrión |
ui/notifications/tool-input | Recibir los argumentos de la llamada a la herramienta |
ui/notifications/tool-result | Recibir el resultado de la herramienta |
tools/call | Llamar a una herramienta del servidor desde la interfaz |
ui/message | Enviar un mensaje de seguimiento en la conversación |
ui/update-model-context | Informar al modelo de una selección o modificación actual |
Lado del servidor: declarar el recurso y la herramienta
Volvamos al servidor de notas de la Lección 4. El paquete @modelcontextprotocol/ext-apps (en la versión 1.x con el SDK v1) proporciona dos ayudantes: registerAppResource, que aplica el tipo MIME correcto expuesto por la constante RESOURCE_MIME_TYPE de forma predeterminada, y registerAppTool, que requiere los metadatos de la interfaz.
import { readFileSync } from "node:fs";
import {
registerAppResource,
registerAppTool,
RESOURCE_MIME_TYPE,
} from "@modelcontextprotocol/ext-apps/server";
const URI_CARTE = "ui://widget/notes-v1.html"; // versionado: esta es una clave de caché
const carteHtml = readFileSync("public/notes-widget.html", "utf8");
// Añadir dentro de creerServeur(), junto a list_notes y add_note
registerAppResource(server, "notes-widget", URI_CARTE, {}, async () => ({
contents: [{ uri: URI_CARTE, mimeType: RESOURCE_MIME_TYPE, text: carteHtml }],
}));
registerAppTool(
server,
"show_notes",
{
title: "Mostrar notas",
description:
"Muestra las notas en una tarjeta. Para mostrar solo un subconjunto, llama primero a 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(s) mostrada(s).` }],
})
);
Solo show_notes lleva la interfaz. Este es el desacoplamiento que OpenAI recomienda: si cada herramienta devolviera una plantilla, ChatGPT volvería a dibujar el iframe con demasiada frecuencia. Las herramientas de datos (list_notes, add_note) buscan, calculan o modifican y devuelven solo su resultado; las herramientas de renderizado reciben datos finales y devuelven la plantilla. El modelo puede así trabajar sobre los datos —filtrar, cruzar referencias— antes de decidir mostrarlos, y la tarjeta aparece solo una vez, con un contexto verificado. Indica la dependencia en la descripción de la herramienta de renderizado, como se muestra arriba.
Lado del iframe: el puente JSON-RPC
El componente encaja aquí en un único archivo HTML, sin paso de compilación. Abre el diálogo con el anfitrión y luego muestra cada resultado de herramienta que recibe.
<!doctype html>
<html lang="en">
<head><meta charset="utf-8" /><title>Notas</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; // nunca innerHTML con datos recibidos
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>
El resultado recibido son datos no fiables: muéstralos con textContent, nunca inyectándolos como HTML. Para una interfaz más rica, el mismo paquete proporciona una clase App del lado del navegador que encapsula este puente (recepción de resultados, llamada a herramientas), para integrarla en un paquete construido con esbuild; el repositorio de ejemplos de OpenAI muestra componentes React completos.
Elegir una presentación
Comienza con la visualización en línea y solicita más espacio solo si el flujo de trabajo lo requiere:
| Presentación | Uso |
|---|---|
| Tarjeta en línea | Un resultado específico, una confirmación, unas pocas acciones, sin navegación profunda |
| Carrusel en línea | Navegar y elegir entre unas pocas opciones visuales similares |
| Pantalla completa | Una tarea rica: mapa, lienzo de edición, exploración detallada; el área de entrada de ChatGPT sigue disponible |
| Imagen en imagen | Una actividad en curso que debe permanecer visible durante la conversación: sesión en directo, juego, vídeo |
Extensiones específicas de ChatGPT
Una vez establecido el flujo de aplicaciones MCP, ChatGPT ofrece extensiones a través de window.openai, que deben usarse solo para lo que el estándar no cubre. Para necesidades comunes, prefiere el estándar; los alias de ChatGPT siguen disponibles para integraciones existentes:
| Necesidad | Estándar de aplicaciones MCP | Alias de ChatGPT |
|---|---|---|
| Adjuntar una herramienta a una interfaz | _meta.ui.resourceUri | _meta["openai/outputTemplate"] |
| Recibir argumentos | ui/initialize + ui/notifications/tool-input | window.openai.toolInput |
| Recibir resultado | ui/notifications/tool-result | window.openai.toolOutput |
| Llamar a una herramienta | tools/call | window.openai.callTool |
| Enviar un mensaje de seguimiento | ui/message | window.openai.sendFollowUpMessage |
Las extensiones sin equivalente estándar cubren el pago integrado (requestCheckout), archivos (uploadFile, selectFiles, getFileDownloadUrl), ventanas modales gestionadas por el anfitrión (requestModal) y la persistencia del estado del componente (widgetState, setWidgetState). Detecta cada capacidad antes de usarla, con una alternativa cuando sea posible, y nunca pruebes el nombre del anfitrión, prueba la función:
const openai = typeof window !== "undefined" ? window.openai : undefined;
if (openai?.requestModal) {
await openai.requestModal({ template: "ui://widget/details-v1.html" });
} else {
document.body.textContent = "Este anfitrión no admite ventanas modales.";
}
Tres tipos de estado
| Estado | Propietario | Duración | Ejemplos |
|---|---|---|---|
| Datos de negocio, fuente de la verdad | Servidor MCP o servicio externo | Larga | Tareas, tickets, documentos |
| Estado de la interfaz, efímero | Instancia del componente | Duración de su visualización | Fila seleccionada, panel abierto, orden de clasificación |
| Estado duradero entre sesiones | Almacenamiento que controlas | Entre conversaciones y dispositivos | Filtros guardados, modo de visualización |
Los datos de negocio permanecen en el servidor: la interfaz llama a una herramienta, el servidor valida y actualiza, y luego devuelve el estado de referencia, que la interfaz muestra manteniendo lo relativo a la presentación. Cuando el modelo necesita conocer una selección, envíala mediante ui/update-model-context. window.openai.setWidgetState (síncrono, sin await) preserva el estado de una instancia, no los datos de negocio. El estado duradero va en tu almacenamiento, tras autenticación; evita localStorage, que no ofrece ni continuidad entre dispositivos ni fiabilidad en un iframe aislado.
Política de seguridad de contenido
El componente declara, en sus metadatos de recurso (_meta.ui.csp), los dominios exactos que utiliza: connectDomains para llamadas a la API, resourceDomains para scripts, estilos e imágenes, y frameDomains solo si debe integrar iframes específicos —los marcos anidados están bloqueados por defecto. Mantén estas listas lo más estrechas posible: la revisión del plugin compara la política declarada con el comportamiento real de la interfaz. Y trata el URI del recurso como una clave de caché: para cada cambio incompatible en el HTML, JavaScript o CSS, publica un nuevo URI y actualiza las herramientas que hacen referencia a él.
Dos detalles finales: el anfitrión refleja el idioma del usuario en document.documentElement.lang, que debe usarse para traducir y formatear fechas y números; y la biblioteca @openai/apps-sdk-ui proporciona botones, tarjetas y campos que coinciden con ChatGPT si no quieres rediseñar todo.
Puntos clave
- Una interfaz es un recurso
ui://de tipotext/html;profile=mcp-app, adjunto a una herramienta mediante_meta.ui.resourceUri - El componente se comunica con el anfitrión mediante JSON-RPC (
ui/initialize,tools/call,ui/notifications/tool-result…) - Separa las herramientas de datos y las de renderizado: solo la herramienta de renderizado lleva la plantilla
window.openaiproporciona solo extensiones, que deben detectarse antes de su uso- Datos de negocio en el servidor, CSP estrecha, URI de recurso versionado