build-mcp-app

Eine MCP-App erstellen (interaktive UI-Widgets)

Eine MCP-App ist ein Standard-MCP-Server, der zusätzlich UI-Ressourcen bereitstellt – interaktive Komponenten, die direkt in der Chat-Oberfläche gerendert werden. Einmal erstellt, läuft sie in Claude und ChatGPT sowie auf jedem anderen Host, der die App-Oberfläche implementiert.

Die Benutzeroberfläche ist eine zusätzliche Ebene. Im Hintergrund kommen nach wie vor dieselben Tools, Ressourcen und dasselbe Wire-Protokoll zum Einsatz. Wenn Sie noch nie einen einfachen MCP-Server erstellt haben, deckt der build-mcp-server behandelt dieser Skill die Basisschicht. Dieser Skill fügt darüber hinaus Widgets hinzu.

Testen in Claude: Füge den Server als benutzerdefinierten Connector in claude.ai hinzu (über einen Cloudflare-Tunnel für die lokale Entwicklung) – dadurch wird die echte Iframe-Sandbox genutzt und hostContext. Siehe https://claude.com/docs/connectors/building/testing.

Besonderheiten des Claude-Hosts

• hostContext.safeAreaInsets: {top, right, bottom, left} (px) – diese Werte müssen für Notches und das Composer-Overlay eingehalten werden.
• Die Einreichung in das Verzeichnis erfordert OAuth oder eine authentifizierungsfreie Verbindung (none) – „static bearer“ ist nur für den privaten Einsatz vorgesehen und verhindert die Aufnahme in die Liste – sowie annotations sowie 3–5 PNG-Screenshots; siehe references/directory-checklist.md.

Wenn ein Widget besser ist als reiner Text

Füge keine Benutzeroberfläche um ihrer selbst willen hinzu – die meisten Tools geben Text oder JSON problemlos zurück. Füge ein Widget hinzu, wenn einer der folgenden Punkte zutrifft:

Wenn keiner der Punkte zutrifft, verzichte auf das Widget. Text lässt sich schneller erstellen und ist für den Nutzer schneller.

Widgets vs. Elicitation – richtig entscheiden

Bevor du ein Widget erstellst, prüfe, ob die Datenabfrage dies abdeckt. Die Datenabfrage ist spezifikationskonform, erfordert keinen UI-Code und funktioniert in jedem kompatiblen Host.

Wenn die Elicitation dies abdeckt, nutze sie. Siehe ../build-mcp-server/references/elicitation.md.

Architektur: zwei Bereitstellungsformen

Remote-MCP-App (am häufigsten)

Gehosteter Streamable-HTTP-Server. Widget-Vorlagen werden als Ressourcen bereitgestellt; Tool-Ergebnisse verweisen auf diese. Der Host ruft die Ressource ab, rendert sie in einer Iframe-Sandbox und vermittelt Nachrichten zwischen dem Widget und Claude.

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

MCPB-verpackte MCP-App (lokal + UI)

Gleicher Widget-Mechanismus, jedoch läuft der Server lokal innerhalb eines MCPB-Bundles. Verwenden Sie diese Variante, wenn das Widget eine lokale Anwendung steuern muss – z. B. einen Dateiauswähler, der die lokale Festplatte durchsucht, oder einen Dialog, der eine Desktop-App steuert.

Für die MCPB-Paketierungsmechanismen beziehen Sie sich bitte auf die „build-mcpb“-Funktion. Alle folgenden Informationen gelten für beide Formen.

Wie Widgets an Tools angehängt werden

Ein Widget-fähiges Tool verfügt über zwei separate Registrierungen:

1. Das Tool deklariert eine UI-Ressource über _meta.ui.resourceUri. Sein Handler gibt reinen Text/JSON zurück – NICHT den HTML-Code.
2. Die Ressource wird separat registriert und stellt den HTML-Code bereit.

Wenn Claude das Tool aufruft, sieht der Host _meta.ui.resourceUri, ruft diese Ressource ab, rendert sie in einem iframe und leitet den Rückgabewert des Tools über das ontoolresult Ereignis in den iframe weiter.

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
    }],
  }),
);

Das URI-Schema ui:// entspricht der Konvention. Der MIME-Typ MUSS RESOURCE_MIME_TYPE ("text/html;profile=mcp-app") – nur so weiß der Host, dass er es als interaktiven Iframe rendern muss und nicht einfach nur den Quellcode anzeigen darf.

Widget-Laufzeitumgebung — die App Klasse

Innerhalb des iframes kommuniziert Ihr Skript mit dem Host über die App Klasse aus @modelcontextprotocol/ext-apps. Dabei handelt es sich um eine dauerhafte bidirektionale Verbindung – das Widget bleibt so lange aktiv, wie die Kommunikation besteht, empfängt neue Tool-Ergebnisse und sendet Benutzeraktionen.

<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>

Der /*__EXT_APPS_BUNDLE__*/ Platzhalter wird beim Start vom Server durch den Inhalt von @modelcontextprotocol/ext-apps/app-with-deps – siehe references/iframe-sandbox.md , warum dies notwendig ist, und das Rewrite-Snippet. Verwenden Sie nicht import { App } from "https://esm.sh/..."; die CSP-Regeln des iframes blockieren das Abrufen transitiver Abhängigkeiten, und das Widget wird leer gerendert.

sendMessage Dies ist der typische Ablauf: „Der Benutzer hat etwas ausgewählt, teile es Claude mit“. updateModelContext dient für Zustände, die Claude kennen sollte, die aber den Chat nicht überladen dürfen. openLink ist für jede Navigation nach außen erforderlich — window.open und werden durch das Sandbox-Attribut blockiert.

Was Widgets nicht können:

• Auf das DOM, die Cookies oder den Speicher der Host-Seite zugreifen
• Netzwerkaufrufe an beliebige Ursprünge tätigen (CSP-beschränkt – Umleitung über callServerTool)
• Popups öffnen oder direkt navigieren – verwenden Sie app.openLink({url})
• Fremde Bilder zuverlässig laden – inline als data: URLs serverseitig

Halten Sie Widgets klein und zweckgebunden. Ein Auswahldialog wählt aus. Ein Diagramm zeigt Daten an. Bauen Sie keine komplette Unteranwendung innerhalb des iframe auf – teilen Sie sie in mehrere Tools mit fokussierten Widgets auf.

Grundgerüst: minimales Auswahl-Widget

Installation:

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

Server (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);

Für rein lokal laufende Widget-Apps (die eine Desktop-App steuern oder lokale Dateien lesen) tauschen Sie den Transport gegen StdioServerTransport und verpacken Sie das Widget über die build-mcpb Skill verpacken.

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>

Weitere Informationen references/widget-templates.md für weitere Widget-Formate.

Designhinweise, die dir eine Neuprogrammierung ersparen

Ein Widget pro Tool. Widerstehe dem Drang, ein Mega-Widget zu erstellen, das alles kann. Ein Tool → ein fokussiertes Widget → eine klare Ergebnisform. Claude kann damit viel besser umgehen.

Die Werkzeugbeschreibung muss das Widget erwähnen. Claude sieht nur die Werkzeugbeschreibung, wenn er entscheidet, was er aufrufen soll. „Öffnet einen interaktiven Auswahl-Dialog“ in der Beschreibung ist das, was Claude dazu veranlasst, darauf zurückzugreifen, anstatt eine ID zu erraten.

Widgets sind zur Laufzeit optional. Hosts, die die App-Oberfläche nicht unterstützen, ignorieren _meta.ui und rendern den Textinhalt des Tools wie gewohnt. Da Ihr Tool-Handler bereits aussagekräftigen Text/JSON (die Daten des Widgets) zurückgibt, erfolgt die Herabstufung automatisch – Claude sieht die Daten direkt statt über das Widget.

Warten Sie bei schreibgeschützten Tools nicht auf Widget-Ergebnisse. Ein Widget, das lediglich Daten anzeigt (Diagramm, Vorschau), sollte keine Benutzeraktion erfordern, um abgeschlossen zu werden. Geben Sie das Anzeige-Widget und eine Textzusammenfassung im selben Ergebnis zurück, damit Claude ohne Wartezeit weiterdenken kann.

Teilen Sie das Layout nach der Anzahl der Elemente auf, nicht nach der Anzahl der Tools. Wenn ein Anwendungsfall „ein Ergebnis im Detail anzeigen“ lautet und ein anderer „viele Ergebnisse nebeneinander anzeigen“, erstellen Sie nicht zwei Tools – erstellen Sie ein Tool, das items[]und das Widget das Layout auswählen lässt: items.length === 1 → Detailansicht, > 1 → Karussell. Das hält das Serverschema einfach und lässt Claude die Anzahl auf natürliche Weise bestimmen.

Fügen Sie Claudes Schlussfolgerung in die Nutzdaten ein. Ein kurzes note Feld bei jedem Element (warum Claude es ausgewählt hat), das als Callout auf der Karte dargestellt wird, liefert den Nutzern die Begründung direkt neben der Auswahl. Erwähne dieses Feld in der Tool-Beschreibung, damit Claude es ausfüllt.

Normalisieren Sie die Bildformen serverseitig. Wenn Ihre Datenquelle Bilder mit stark variierenden Seitenverhältnissen zurückgibt, wandeln Sie diese vor dem Abruf für die Inline-Daten-URL in eine vorhersehbare Variante um (z. B. quadratisch begrenzt). Weisen Sie dann dem Bildcontainer des Widgets eine feste aspect-ratio + object-fit: contain , damit alles zentriert angezeigt wird.

Passen Sie sich dem Host-Theme an. app.getHostContext()?.theme (nach connect()) sowie app.onhostcontextchanged für Live-Aktualisierungen. Schalten Sie eine .dark Klasse ein , Farben in benutzerdefinierten CSS-Props mit einem :root.dark {} Überschreibungsblock, legen Sie color-scheme. Deaktivieren Sie mix-blend-mode: multiply im Dunkelmodus – dadurch verschwinden Bilder.

Testen

Claude Desktop – aktuelle Builds erfordern noch die command/args Konfigurationsform (keine native "type": "http"). Mit mcp-remote und erzwinge den http-only Transport erzwingen, damit die SSE-Prüfung die Aushandlung der Widget-Fähigkeiten nicht unterbindet:

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

Desktop speichert UI-Ressourcen intensiv im Cache. Beenden Sie nach der Bearbeitung des Widget-HTMLs die Anwendung vollständig (⌘Q / Alt+F4, nicht das Fenster schließen) und starten Sie sie neu, um ein vollständiges Neuladen der Ressourcen zu erzwingen.

Headless-JSON-RPC-Schleife – schnelle Iteration ohne Klicken durch den 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

Das sleep hält stdin lange genug offen, um alle Antworten zu erfassen. Parsen Sie die jsonl-Ausgabe mit jq oder einem Python-Einzeiler.

Widget-Entwicklungsschleife – Umgehen Sie den ⌘Q-Neustart-Zyklus vollständig, indem Sie den eingebetteten Widget-HTML-Code über eine einfache GET-Route mit einem gefälschten ExtApps Shim, der ontoolresult über einen Abfrageparameter:

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));
});

Öffne http://localhost:3000/widget-preview?payload={"rows":[...]} in einem normalen Browser-Tab und führen Sie die Überprüfung mit den üblichen Entwicklertools durch.

Host-Fallback – Verwende einen Host ohne die App-Oberfläche (oder den MCP Inspector) und stelle sicher, dass der Textinhalt des Tools auch unter diesen Bedingungen einwandfrei dargestellt wird.

CSP-Debugging – Öffnen Sie die eigene DevTools-Konsole des Iframes. CSP-Verstöße sind der Hauptgrund dafür, dass Widgets stillschweigend fehlschlagen (leeres Rechteck, kein Fehler in der Hauptkonsole). Siehe references/iframe-sandbox.md.

Referenzdateien

• references/iframe-sandbox.md — CSP-/Sandbox-Einschränkungen, das Bundle-Inlining-Muster, Bildverarbeitung, Host-Theming
• references/widget-templates.md — wiederverwendbare HTML-Gerüste für Auswahlfelder / Bestätigungsfelder / Fortschrittsanzeigen / Anzeigen
• references/apps-sdk-messages.md — die App Klassen-API: Nachrichtenaustausch zwischen Widget ↔ Host ↔ Server, Lebenszyklus und Ersetzung
• references/payload-budgeting.md — Größenbeschränkungen für Host-Tool-Ergebnisse, „Prune-then-Truncate“, umfangreiche Assets über callServerTool
• references/abuse-protection.md — Anthropic-CIDRs für den ausgehenden Datenverkehr, gestaffelte Ratenbegrenzung, trust proxy, Antwort-Caching
• references/directory-checklist.md — Vorabprüfung für die Einreichung in das Connector-Verzeichnis