Ir al contenido principal
Español— Elegir un idioma
Menú

Añadir una interfaz con aplicaciones MCP

Lección 6 de 14 Actualizado el 3 de noviembre de 2026 Desarrollador
En esta página
  1. Cuándo añadir una interfaz
  2. El principio de las aplicaciones MCP
  3. Lado del servidor: declarar el recurso y la herramienta
  4. Lado del iframe: el puente JSON-RPC
  5. Elegir una presentación
  6. Extensiones específicas de ChatGPT
  7. Tres tipos de estado
  8. Política de seguridad de contenido
  9. Puntos clave

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

MensajeFunción
ui/initialize y luego ui/notifications/initializedAbrir el diálogo con el anfitrión
ui/notifications/tool-inputRecibir los argumentos de la llamada a la herramienta
ui/notifications/tool-resultRecibir el resultado de la herramienta
tools/callLlamar a una herramienta del servidor desde la interfaz
ui/messageEnviar un mensaje de seguimiento en la conversación
ui/update-model-contextInformar 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ónUso
Tarjeta en líneaUn resultado específico, una confirmación, unas pocas acciones, sin navegación profunda
Carrusel en líneaNavegar y elegir entre unas pocas opciones visuales similares
Pantalla completaUna tarea rica: mapa, lienzo de edición, exploración detallada; el área de entrada de ChatGPT sigue disponible
Imagen en imagenUna 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:

NecesidadEstándar de aplicaciones MCPAlias de ChatGPT
Adjuntar una herramienta a una interfaz_meta.ui.resourceUri_meta["openai/outputTemplate"]
Recibir argumentosui/initialize + ui/notifications/tool-inputwindow.openai.toolInput
Recibir resultadoui/notifications/tool-resultwindow.openai.toolOutput
Llamar a una herramientatools/callwindow.openai.callTool
Enviar un mensaje de seguimientoui/messagewindow.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

EstadoPropietarioDuraciónEjemplos
Datos de negocio, fuente de la verdadServidor MCP o servicio externoLargaTareas, tickets, documentos
Estado de la interfaz, efímeroInstancia del componenteDuración de su visualizaciónFila seleccionada, panel abierto, orden de clasificación
Estado duradero entre sesionesAlmacenamiento que controlasEntre conversaciones y dispositivosFiltros 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 tipo text/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.openai proporciona solo extensiones, que deben detectarse antes de su uso
  • Datos de negocio en el servidor, CSP estrecha, URI de recurso versionado