Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Adicionar uma interface com aplicações MCP

Aula 6 de 14 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. Quando adicionar uma interface
  2. O princípio das Aplicações MCP
  3. Lado do servidor: declarar o recurso e a ferramenta
  4. Lado do iframe: a ponte JSON-RPC
  5. Escolher uma apresentação
  6. Extensões específicas do ChatGPT
  7. Três tipos de estado
  8. Política de Segurança de Conteúdo (CSP)
  9. Pontos-chave

Lição reescrita a 3 de novembro de 2026 com base na página Add UI to your MCP server da documentação de Plugins da OpenAI e no código para @modelcontextprotocol/ext-apps 1.7.5. A lição anterior descrevia “widgets” (defineWidget) de um SDK inexistente; uma interface é um recurso de Aplicações MCP renderizado pelo ChatGPT num iframe. Fontes: Add UI to your MCP server · Especificação de Aplicações MCP.

Quando adicionar uma interface

A interface é opcional. Adicione uma quando o utilizador precisar de inspecionar, comparar, modificar, confirmar ou navegar por informações estruturadas — e mantenha as suas ferramentas úteis mesmo sem ela, para que o ChatGPT e o Codex possam conduzir o fluxo de trabalho em clientes que não apresentam um componente.

O princípio das Aplicações MCP

O ChatGPT implementa o padrão aberto de Aplicações MCP. O servidor declara um recurso de interface, identificado por um URI ui://… e servido com o tipo MIME text/html;profile=mcp-app; uma ferramenta liga-se a ele através de _meta.ui.resourceUri. Quando esta ferramenta é chamada, o ChatGPT apresenta o recurso num iframe, ao lado da conversa. O componente comunica com o anfitrião via JSON-RPC utilizando postMessage:

MensagemFunção
ui/initialize seguido de ui/notifications/initializedAbrir o diálogo com o anfitrião
ui/notifications/tool-inputReceber os argumentos da chamada da ferramenta
ui/notifications/tool-resultReceber o resultado da ferramenta
tools/callChamar uma ferramenta do servidor a partir da interface
ui/messageEnviar uma mensagem de acompanhamento na conversa
ui/update-model-contextInformar o modelo sobre uma seleção ou modificação atual

Lado do servidor: declarar o recurso e a ferramenta

Vamos revisitar o servidor de notas da Lição 4. O pacote @modelcontextprotocol/ext-apps (na versão 1.x com SDK v1) fornece dois auxiliares: registerAppResource, que aplica o tipo MIME correto exposto pela constante RESOURCE_MIME_TYPE por predefinição, e registerAppTool, que requer os metadados da interface.

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: isto é uma chave de cache
const carteHtml = readFileSync("public/notes-widget.html", "utf8");

// Adicionar dentro de creerServeur(), junto 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: "Mostrar notas",
    description:
      "Apresenta as notas num cartão. Para mostrar apenas um subconjunto, chame list_notes primeiro.",
    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) apresentada(s).` }],
  })
);

Apenas show_notes transporta a interface. Este é o desacoplamento que a OpenAI recomenda: se cada ferramenta devolvesse um modelo, o ChatGPT redesenharia o iframe com demasiada frequência. As ferramentas de dados (list_notes, add_note) pesquisam, calculam ou modificam e devolvem apenas o seu resultado; as ferramentas de renderização recebem dados finais e devolvem o modelo. O modelo pode assim trabalhar sobre os dados — filtrar, cruzar referências — antes de decidir apresentar, e o cartão aparece apenas uma vez, com um contexto verificado. Indique a dependência na descrição da ferramenta de renderização, como mostrado acima.

Lado do iframe: a ponte JSON-RPC

O componente encaixa aqui num único ficheiro HTML, sem etapa de compilação. Abre o diálogo com o anfitrião e, em seguida, apresenta cada resultado de ferramenta que recebe.

<!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 em dados recebidos
            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>

O resultado recebido são dados não confiáveis: apresente-os com textContent, nunca injetando-os como HTML. Para uma interface mais rica, o mesmo pacote fornece uma classe App do lado do navegador que encapsula esta ponte (receber resultados, chamar ferramentas), a ser integrada num pacote construído com esbuild; o repositório de exemplos da OpenAI mostra componentes React completos.

Escolher uma apresentação

Comece com a apresentação inline e solicite mais espaço apenas se o fluxo de trabalho o exigir:

ApresentaçãoUtilização
Cartão inlineUm resultado direcionado, uma confirmação, algumas ações, sem navegação profunda
Carrossel inlineNavegar e escolher entre algumas opções visuais semelhantes
Ecrã completoUma tarefa rica: mapa, tela de edição, exploração detalhada; a área de entrada do ChatGPT permanece disponível
Imagem na imagem (Picture-in-picture)Uma atividade em curso que deve permanecer visível durante a conversa: sessão ao vivo, jogo, vídeo

Extensões específicas do ChatGPT

Uma vez estabelecido o fluxo das Aplicações MCP, o ChatGPT oferece extensões via window.openai, a serem usadas apenas para o que o padrão não cobre. Para necessidades comuns, prefira o padrão; os aliases do ChatGPT permanecem disponíveis para integrações existentes:

NecessidadePadrão Aplicações MCPAlias ChatGPT
Ligar uma ferramenta a uma interface_meta.ui.resourceUri_meta["openai/outputTemplate"]
Receber argumentosui/initialize + ui/notifications/tool-inputwindow.openai.toolInput
Receber resultadoui/notifications/tool-resultwindow.openai.toolOutput
Chamar uma ferramentatools/callwindow.openai.callTool
Enviar uma mensagem de acompanhamentoui/messagewindow.openai.sendFollowUpMessage

As extensões sem equivalente padrão cobrem checkout integrado (requestCheckout), ficheiros (uploadFile, selectFiles, getFileDownloadUrl), janelas modais geridas pelo anfitrião (requestModal) e persistência do estado do componente (widgetState, setWidgetState). Detete cada capacidade antes de a usar, com uma alternativa quando possível — e nunca teste o nome do anfitrião, teste a função:

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ão não suporta janelas modais.";
}

Três tipos de estado

EstadoProprietárioDuraçãoExemplos
Dados de negócio, fonte da verdadeServidor MCP ou serviço externoLongaTarefas, tickets, documentos
Estado da interface, efémeroInstância do componenteDuração da sua exibiçãoLinha selecionada, painel aberto, ordem de classificação
Estado duradouro entre sessõesArmazenamento que controlaEntre conversas e dispositivosFiltros guardados, modo de exibição

Os dados de negócio permanecem no servidor: a interface chama uma ferramenta, o servidor valida e atualiza, e depois devolve o estado de referência, que a interface apresenta mantendo o que diz respeito à apresentação. Quando o modelo precisa de conhecer uma seleção, envie-a via ui/update-model-context. window.openai.setWidgetState (síncrono, sem await) preserva o estado de uma instância, não os dados de negócio. O estado duradouro vai para o seu armazenamento, atrás de autenticação; evite localStorage, que não oferece continuidade entre dispositivos nem fiabilidade num iframe isolado.

Política de Segurança de Conteúdo (CSP)

O componente declara, nos seus metadados de recurso (_meta.ui.csp), os domínios exatos que utiliza: connectDomains para chamadas API, resourceDomains para scripts, estilos e imagens, frameDomains apenas se tiver de integrar iframes específicos — frames aninhadas são bloqueadas por predefinição. Mantenha estas listas o mais restritas possível: a revisão do plugin compara a política declarada com o comportamento real da interface. E trate o URI do recurso como uma chave de cache: para cada alteração incompatível no HTML, JavaScript ou CSS, publique um novo URI e atualize as ferramentas que o referenciam.

Dois detalhes finais: o anfitrião reflete o idioma do utilizador em document.documentElement.lang, a ser usado para traduzir e formatar datas e números; e a biblioteca @openai/apps-sdk-ui fornece botões, cartões e campos que correspondem ao ChatGPT se não quiser redesenhar tudo.

Pontos-chave

  • Uma interface é um recurso ui:// do tipo text/html;profile=mcp-app, ligado a uma ferramenta via _meta.ui.resourceUri
  • O componente comunica com o anfitrião via JSON-RPC (ui/initialize, tools/call, ui/notifications/tool-result…)
  • Separe ferramentas de dados e ferramentas de renderização: apenas a ferramenta de renderização transporta o modelo
  • window.openai fornece apenas extensões, a serem detetadas antes do uso
  • Dados de negócio no servidor, CSP restrita, URI de recurso versionado