build-mcp-app

Crie um aplicativo MCP (componentes interativos da interface do usuário)

Um aplicativo MCP é um servidor MCP padrão que também fornece recursos de interface do usuário — componentes interativos renderizados diretamente na área de bate-papo. Crie uma vez e execute no Claude, no ChatGPT e em qualquer outro host que implemente a interface do aplicativo.

A camada de interface do usuário é adicional. Nos bastidores, ainda são as mesmas ferramentas, os mesmos recursos e o mesmo protocolo de comunicação. Se você nunca criou um servidor MCP simples antes, a build-mcp-server skill aborda a camada básica. Esta skill adiciona widgets sobre ela.

Testando no Claude: adicione o servidor como um conector personalizado no claude.ai (por meio de um túnel do Cloudflare para desenvolvimento local) — isso testa a sandbox real do iframe e hostContext. Consulte https://claude.com/docs/connectors/building/testing.

Especificações do host do Claude

• hostContext.safeAreaInsets: {top, right, bottom, left} (px) — respeite esses valores para os notches e a sobreposição do compositor.
• O envio para o diretório requer OAuth ou autenticação sem OAuth (none) — o bearer estático é exclusivo para implantação privada e bloqueia a listagem — além de annotations e de 3 a 5 capturas de tela em PNG; consulte references/directory-checklist.md.

Quando um widget é melhor que texto simples

Não adicione uma interface de usuário apenas por adicionar — a maioria das ferramentas funciona bem retornando texto ou JSON. Adicione um widget quando uma das seguintes condições for verdadeira:

Se nenhuma dessas condições se aplicar, ignore o widget. O texto é mais rápido de criar e mais rápido para o usuário.

Widgets x Elicitação — escolha o caminho correto

Antes de criar um widget, verifique se a elicitação já cobre essa funcionalidade. A elicitação é nativa da especificação, não requer código de interface do usuário e funciona em qualquer host compatível.

Se a elicitação já cobrir isso, use-a. Veja ../build-mcp-server/references/elicitation.md.

Arquitetura: dois modelos de implantação

Aplicativo MCP remoto (mais comum)

Servidor HTTP streamable hospedado. Os modelos de widget são servidos como recursos; os resultados da ferramenta fazem referência a eles. O host busca o recurso, o renderiza em uma sandbox iframe e faz a mediação de mensagens entre o widget e o Claude.

┌──────────┐  tools/call   ┌────────────┐
│  Claude  │─────────────> │ MCP server │
│   host   │<── result ────│  (remote)  │
│          │  + widget ref │            │
│          │               │            │
│          │ resources/read│            │
│          │─────────────> │  widget    │
│ ┌──────┐ │<── template ──│  HTML/JS   │
│ │iframe│ │               └────────────┘
│ │widget│ │
│ └──────┘ │
└──────────┘

Aplicativo MCP empacotado no MCPB (local + interface do usuário)

O mesmo mecanismo de widget, mas o servidor é executado localmente dentro de um pacote MCPB. Use isso quando o widget precisar controlar um aplicativo local — por exemplo, um seletor de arquivos que navega pelo disco local real, uma caixa de diálogo que controla um aplicativo de desktop.

Para os mecanismos de empacotamento do MCPB, consulte a habilidade “build-mcpb”. Tudo o que se segue se aplica a ambas as formas.

Como os widgets se associam às ferramentas

Uma ferramenta habilitada para widgets possui dois registros distintos:

1. A ferramenta declara um recurso de interface do usuário por meio de _meta.ui.resourceUri. Seu manipulador retorna texto simples/JSON — NÃO o HTML.
2. O recurso é registrado separadamente e fornece o HTML.

Quando o Claude chama a ferramenta, o host vê _meta.ui.resourceUri, busca esse recurso, o renderiza em um iframe e canaliza o valor de retorno da ferramenta para o iframe por meio do ontoolresult evento.

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { registerAppTool, registerAppResource, RESOURCE_MIME_TYPE }
  from "@modelcontextprotocol/ext-apps/server";
import { z } from "zod";const server = new McpServer({ name: "contacts", version: "1.0.0" });// 1. The tool — returns DATA, declares which UI to show
registerAppTool(server, "pick_contact", {
  description: "Open an interactive contact picker",
  annotations: { title: "Pick Contact", readOnlyHint: true },
  inputSchema: { filter: z.string().optional() },
  _meta: { ui: { resourceUri: "ui://widgets/contact-picker.html" } },
}, async ({ filter }) => {
  const contacts = await db.contacts.search(filter);
  // Plain JSON — the widget receives this via ontoolresult
  return { content: [{ type: "text", text: JSON.stringify(contacts) }] };
});// 2. The resource — serves the HTML
registerAppResource(
  server,
  "Contact Picker",
  "ui://widgets/contact-picker.html",
  {},
  async () => ({
    contents: [{
      uri: "ui://widgets/contact-picker.html",
      mimeType: RESOURCE_MIME_TYPE,
      text: pickerHtml,  // your HTML string
    }],
  }),
);

O esquema de URI ui:// é convencional. O tipo MIME DEVE ser RESOURCE_MIME_TYPE ("text/html;profile=mcp-app") — é assim que o host sabe que deve renderizá-lo como um iframe interativo, e não apenas exibir o código-fonte.

Tempo de execução do widget — o App classe

Dentro do iframe, seu script se comunica com o host por meio da App classe de @modelcontextprotocol/ext-apps. Trata-se de uma conexão bidirecional persistente — o widget permanece ativo enquanto a comunicação estiver ativa, recebendo novos resultados da ferramenta e enviando ações do usuário.

<script type="module">
  /* ext-apps bundle inlined at build time → globalThis.ExtApps */
  /*__EXT_APPS_BUNDLE__*/
  const { App } = globalThis.ExtApps;  const app = new App({ name: "ContactPicker", version: "1.0.0" }, {});  // Set handlers BEFORE connecting
  app.ontoolresult = ({ content }) => {
    const contacts = JSON.parse(content[0].text);
    render(contacts);
  };  await app.connect();  // Later, when the user clicks something:
  function onPick(contact) {
    app.sendMessage({
      role: "user",
      content: [{ type: "text", text: `Selected contact: ${contact.id}` }],
    });
  }
script>

O /*__EXT_APPS_BUNDLE__*/ placeholder é substituído pelo servidor na inicialização pelo conteúdo de @modelcontextprotocol/ext-apps/app-with-deps — veja references/iframe-sandbox.md para saber por que isso é necessário e ver o trecho de reescrita. Não import { App } from "https://esm.sh/..."; o CSP do iframe bloqueia as chamadas de dependências transitivas e o widget é renderizado em branco.

sendMessage é o caminho típico “o usuário escolheu algo, avise o Claude”. updateModelContext é para o estado que o Claude deve conhecer, mas que não deve sobrecarregar o chat. openLink é necessário para qualquer navegação de saída — window.open e são bloqueados pelo atributo sandbox.

O que os widgets não podem fazer:

• Acessar o DOM, os cookies ou o armazenamento da página anfitriã
• Fazer chamadas de rede para origens arbitrárias (restritas por CSP — redirecione por meio de callServerTool)
• Abrir pop-ups ou navegar diretamente — use app.openLink({url})
• Carregar imagens remotas de forma confiável — como data: URLs no lado do servidor

Mantenha os widgets pequenos e com uma única finalidade. Um seletor seleciona. Um gráfico exibe. Não crie um subaplicativo inteiro dentro do iframe — divida-o em várias ferramentas com widgets específicos.

Estrutura básica: widget de seleção minimalista

Instalação:

npm install @modelcontextprotocol/sdk @modelcontextprotocol/ext-apps zod express

Servidor (src/server.ts):

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
import { registerAppTool, registerAppResource, RESOURCE_MIME_TYPE }
  from "@modelcontextprotocol/ext-apps/server";
import express from "express";
import { readFileSync } from "node:fs";
import { createRequire } from "node:module";
import { z } from "zod";const require = createRequire(import.meta.url);
const server = new McpServer({ name: "contact-picker", version: "1.0.0" });// Inline the ext-apps browser bundle into the widget HTML.
// The iframe CSP blocks CDN script fetches — bundling is mandatory.
const bundle = readFileSync(
  require.resolve("@modelcontextprotocol/ext-apps/app-with-deps"), "utf8",
).replace(/export\{([^}]+)\};?\s*$/, (_, body) =>
  "globalThis.ExtApps={" +
  body.split(",").map((p) => {
    const [local, exported] = p.split(" as ").map((s) => s.trim());
    return `${exported ?? local}:${local}`;
  }).join(",") + "};",
);
const pickerHtml = readFileSync("./widgets/picker.html", "utf8")
  .replace("/*__EXT_APPS_BUNDLE__*/", () => bundle);registerAppTool(server, "pick_contact", {
  description: "Open an interactive contact picker. User selects one contact.",
  annotations: { title: "Pick Contact", readOnlyHint: true },
  inputSchema: { filter: z.string().optional().describe("Name/email prefix filter") },
  _meta: { ui: { resourceUri: "ui://widgets/picker.html" } },
}, async ({ filter }) => {
  const contacts = await db.contacts.search(filter ?? "");
  return { content: [{ type: "text", text: JSON.stringify(contacts) }] };
});registerAppResource(server, "Contact Picker", "ui://widgets/picker.html", {},
  async () => ({
    contents: [{ uri: "ui://widgets/picker.html", mimeType: RESOURCE_MIME_TYPE, text: pickerHtml }],
  }),
);const app = express();
app.use(express.json());
app.post("/mcp", async (req, res) => {
  const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
  res.on("close", () => transport.close());
  await server.connect(transport);
  await transport.handleRequest(req, res, req.body);
});
app.listen(process.env.PORT ?? 3000);

Para aplicativos de widgets exclusivamente locais (que controlam um aplicativo de desktop ou leem arquivos locais), troque o transporte para StdioServerTransport e empacote por meio da build-mcpb skill.

Widget (widgets/picker.html):

html>
<meta charset="utf-8" />
<style>
  body { font: 14px system-ui; margin: 0; }
  ul { list-style: none; padding: 0; margin: 0; max-height: 300px; overflow-y: auto; }
  li { padding: 10px 14px; cursor: pointer; border-bottom: 1px solid #eee; }
  li:hover { background: #f5f5f5; }
  .sub { color: #666; font-size: 12px; }
style>
<ul id="list">ul>
<script type="module">
/*__EXT_APPS_BUNDLE__*/
const { App } = globalThis.ExtApps;
(async () => {
  const app = new App({ name: "ContactPicker", version: "1.0.0" }, {});
  const ul = document.getElementById("list");  app.ontoolresult = ({ content }) => {
    const contacts = JSON.parse(content[0].text);
    ul.innerHTML = "";
    for (const c of contacts) {
      const li = document.createElement("li");
      li.innerHTML = `
${c.name}
${c.email}
`;
      li.addEventListener("click", () => {
        app.sendMessage({
          role: "user",
          content: [{ type: "text", text: `Selected contact: ${c.id} (${c.name})` }],
        });
      });
      ul.append(li);
    }
  };  await app.connect();
})();
script>

Consulte references/widget-templates.md para mais formatos de widget.

Notas de design que poupam você de ter que reescrever

Um widget por ferramenta. Resista à tentação de criar um megawidget que faça tudo. Uma ferramenta → um widget específico → um resultado claro. O Claude lida com isso muito melhor.

A descrição da ferramenta deve mencionar o widget. O Claude só vê a descrição da ferramenta ao decidir o que chamar. “Abre um seletor interativo” na descrição é o que faz o Claude recorrer a ela, em vez de adivinhar um ID.

Os widgets são opcionais em tempo de execução. Hosts que não suportam a interface dos aplicativos simplesmente ignoram _meta.ui e exibem o conteúdo de texto da ferramenta normalmente. Como seu manipulador de ferramentas já retorna texto/JSON significativo (os dados do widget), a degradação é automática — o Claude vê os dados diretamente, em vez de por meio do widget.

Não bloqueie com base nos resultados do widget para ferramentas somente leitura. Um widget que apenas exibe dados (gráfico, visualização) não deve exigir uma ação do usuário para ser concluído. Retorne o widget de exibição e um resumo em texto no mesmo resultado para que o Claude possa continuar o raciocínio sem esperar.

Divida o layout por contagem de itens, não por contagem de ferramentas. Se um caso de uso for “mostrar um resultado em detalhes” e outro for “mostrar muitos resultados lado a lado”, não crie duas ferramentas — crie uma ferramenta que aceite items[]e deixe que o widget escolha um layout: items.length === 1 → visualização detalhada, > 1 → carrossel. Isso mantém o esquema do servidor simples e permite que o Claude decida a contagem naturalmente.

Coloque o raciocínio do Claude na carga útil. Um pequeno note campo em cada item (por que o Claude o escolheu), exibido como uma legenda no cartão, fornece aos usuários o raciocínio junto com a escolha. Mencione esse campo na descrição da ferramenta para que o Claude o preencha.

Normalize os formatos das imagens no lado do servidor. Se sua fonte de dados retornar imagens com proporções muito variadas, reescreva-as para uma variante previsível (por exemplo, com bordas quadradas) antes de buscá-las para a URL de dados embutida. Em seguida, atribua ao contêiner de imagem do widget uma largura fixa aspect-ratio + object-fit: contain para que tudo fique centralizado.

Siga o tema do host. app.getHostContext()?.theme (após connect()) mais app.onhostcontextchanged para atualizações em tempo real. Ative ou desative uma .dark classe , mantenha as cores nas propriedades personalizadas do CSS com um :root.dark {} bloco de substituição, defina color-scheme. Desative mix-blend-mode: multiply no modo escuro — isso faz com que as imagens desapareçam.

Testando

Claude Desktop — as compilações atuais ainda exigem a command/args formato de configuração (sem suporte nativo "type": "http"). Envolva com mcp-remote e force o http-only o transporte para que a sonda SSE não interfira na negociação de recursos do widget:

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:3000/mcp",
               "--allow-http", "--transport", "http-only"]
    }
  }
}

O Desktop armazena recursos da interface do usuário em cache de forma agressiva. Após editar o HTML do widget, saia completamente (⌘Q / Alt+F4, não feche a janela) e reinicie para forçar uma nova busca completa pelos recursos.

Loop JSON-RPC sem interface gráfica — iteração rápida sem precisar clicar no Desktop:

# test.jsonl — one JSON-RPC message per line
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"t","version":"0"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/list"}
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"your_tool","arguments":{...}}}(cat test.jsonl; sleep 10) | npx mcp-remote http://localhost:3000/mcp --allow-http

O sleep mantém o stdin aberto por tempo suficiente para coletar todas as respostas. Analise a saída do jsonl com jq ou uma linha única de Python.

Loop de desenvolvimento de widget — evite totalmente o ciclo ⌘Q-reiniciar servindo o HTML do widget embutido em uma rota GET simples com um ExtApps shim que é acionado ontoolresult a partir de um parâmetro de consulta:

app.get("/widget-preview", (_req, res) => {
  const shim = `globalThis.ExtApps={applyHostStyleVariables:()=>{},App:class{
    constructor(){this.h={}} ontoolresult;onhostcontextchanged;
    async connect(){const p=new URLSearchParams(location.search).get("payload");
      if(p)this.ontoolresult?.({content:[{type:"text",text:p}]});}
    getHostContext(){return{theme:"light"}}
    sendMessage(m){console.log("sendMessage",m)} updateModelContext(){}
    callServerTool(){return Promise.resolve({content:[]})} openLink(){} downloadFile(){}
  }};`;
  res.type("html").send(widgetHtml.replace("/*__EXT_APPS_BUNDLE__*/", shim));
});

Abra http://localhost:3000/widget-preview?payload={"rows":[...]} em uma aba normal do navegador e faça iterações com as ferramentas de desenvolvimento comuns.

Fallback de host — use um host sem a interface do aplicativo (ou o MCP Inspector) e confirme se o conteúdo de texto da ferramenta se adapta adequadamente.

Depuração de CSP — abra o próprio console das ferramentas de desenvolvimento do iframe. Violações de CSP são a principal causa de falhas silenciosas dos widgets (retângulo em branco, sem erro no console principal). Consulte references/iframe-sandbox.md.

Arquivos de referência

• references/iframe-sandbox.md — restrições de CSP/sandbox, o padrão de inlining de pacotes, tratamento de imagens, personalização de tema do host
• references/widget-templates.md — estruturas HTML reutilizáveis para seletor / confirmação / progresso / exibição
• references/apps-sdk-messages.md — a App API de classe: troca de mensagens entre widget ↔ host ↔ servidor, ciclo de vida e substituição
• references/payload-budgeting.md — limites de tamanho para resultados de ferramentas no host, “prune-then-truncate”, recursos pesados via callServerTool
• references/abuse-protection.md — CIDRs de saída da Anthropic, limitação de taxa em camadas, trust proxy, armazenamento em cache de respostas
• references/directory-checklist.md — verificação prévia para envio ao diretório de conectores