Adicionar uma interface com aplicações MCP
Nesta página
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-apps1.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:
| Mensagem | Função |
|---|---|
ui/initialize seguido de ui/notifications/initialized | Abrir o diálogo com o anfitrião |
ui/notifications/tool-input | Receber os argumentos da chamada da ferramenta |
ui/notifications/tool-result | Receber o resultado da ferramenta |
tools/call | Chamar uma ferramenta do servidor a partir da interface |
ui/message | Enviar uma mensagem de acompanhamento na conversa |
ui/update-model-context | Informar 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ção | Utilização |
|---|---|
| Cartão inline | Um resultado direcionado, uma confirmação, algumas ações, sem navegação profunda |
| Carrossel inline | Navegar e escolher entre algumas opções visuais semelhantes |
| Ecrã completo | Uma 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:
| Necessidade | Padrão Aplicações MCP | Alias ChatGPT |
|---|---|---|
| Ligar uma ferramenta a uma interface | _meta.ui.resourceUri | _meta["openai/outputTemplate"] |
| Receber argumentos | ui/initialize + ui/notifications/tool-input | window.openai.toolInput |
| Receber resultado | ui/notifications/tool-result | window.openai.toolOutput |
| Chamar uma ferramenta | tools/call | window.openai.callTool |
| Enviar uma mensagem de acompanhamento | ui/message | window.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
| Estado | Proprietário | Duração | Exemplos |
|---|---|---|---|
| Dados de negócio, fonte da verdade | Servidor MCP ou serviço externo | Longa | Tarefas, tickets, documentos |
| Estado da interface, efémero | Instância do componente | Duração da sua exibição | Linha selecionada, painel aberto, ordem de classificação |
| Estado duradouro entre sessões | Armazenamento que controla | Entre conversas e dispositivos | Filtros 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 tipotext/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.openaifornece apenas extensões, a serem detetadas antes do uso- Dados de negócio no servidor, CSP restrita, URI de recurso versionado