mcp-ui: HTML-Oberflächen für MCP-Tools, verdrahtet über _meta.ui.resourceUri

Welches Problem die Bibliothek adressiert und für wen sie gedacht ist

MCP-Server liefern Tool-Ergebnisse bislang als Text oder strukturierte Daten. Ein Assistent kann damit rechnen, aber nichts anzeigen, was ein Nutzer direkt bedienen kann. mcp-ui setzt an dieser Stelle an: Es definiert, wie ein Tool auf eine HTML-Ressource verweist, wie diese Ressource über resources/read abgeholt wird und wie der Host sie in einem iframe rendert. Die Zielgruppe ist damit klar umrissen. Angesprochen sind Autorinnen und Autoren von MCP-Servern, die ihren Tools eine Oberfläche geben wollen, sowie Entwickler von MCP-Hosts, die fremde Tool-UIs einbetten müssen. Wer nur ein Backend ohne UI-Anspruch baut, ist hier falsch.

Das README formuliert den Anspruch, das Projekt habe das Konzept interaktiver UI über MCP geprägt und die MCP Apps Spezifikation beeinflusst. Das ist eine Selbstaussage des Repositories und lässt sich aus dem vorliegenden Material nicht unabhängig prüfen. Faktisch relevant ist die Aussage, dass die Pakete @mcp-ui/* die MCP Apps Spezifikation implementieren und @mcp-ui/client als empfohlenes SDK für MCP Apps Hosts bezeichnet wird.

Der Verdrahtungsmechanismus: _meta.ui.resourceUri und das UIResource-Format

Der Kern des Designs ist eine Verknüpfung über Metadaten. Ein Tool wird mit registerAppTool registriert und bekommt ein Feld _meta mit dem Pfad ui.resourceUri, das auf die zugehörige UI-Ressource zeigt. Der Host erkennt dieses Feld, holt die Ressource über resources/read und rendert sie. Die Ressource selbst wird zuvor mit createUIResource erzeugt und über registerAppResource als Handler registriert. Das README zeigt genau diese drei Schritte in einem TypeScript-Beispiel.

Das Wire-Format ist ein Objekt vom Typ resource mit den Feldern uri, mimeType und entweder text oder blob. Die uri nutzt das Schema ui://, der mimeType lautet text/html;profile=mcp-app. Der Unterschied zwischen text und blob ist rein kodierungstechnisch: einmal Klartext-HTML, einmal Base64. Das ist bewusst schlicht gehalten. Es gibt keine deklarative Komponentenbeschreibung, keine Schema-Datei für Widget-Eigenschaften, keine Versionierung einzelner UI-Bestandteile. Die gesamte Interaktion läuft über HTML und Events, die der Host abfängt.

Zwei Renderer, zwei Generationen von Hosts

Die Client-Seite kennt zwei Komponenten, und diese Unterscheidung ist die wichtigste Entscheidung beim Einstieg. AppRenderer ist der Weg für MCP Apps Hosts. Er bekommt unter anderem client, toolName, toolInput, toolResult und ein sandbox-Objekt mit einer Proxy-URL. Ist client gesetzt, holt der Renderer die Ressource selbst. Die Handler onOpenLink und onMessage fangen Anforderungen aus der eingebetteten UI ab.

UIResourceRenderer richtet sich dagegen an ältere Hosts, die die Ressource direkt in der Tool-Antwort mitliefern. Er nimmt ein resource-Objekt und einen onUIAction-Callback entgegen, der Tool-, Prompt-, Link-, Notify- und Intent-Aktionen verarbeitet. Dieselbe Komponente existiert zusätzlich als Web Component unter dem Tag ui-resource-renderer, das ein resource-Attribut als JSON-String erwartet. Das ist nützlich, wenn die Host-Anwendung nicht in React geschrieben ist.

Bemerkenswert ist, dass beide Renderer HTML über ein iframe einbetten. Daraus folgt eine harte Grenze: Die UI läuft in einem eigenen Dokument und kann nicht direkt auf den DOM des Hosts zugreifen. Jede Interaktion muss als Nachricht über die Grenze gehen. Wer eine eng verzahnte Oberfläche erwartet, die den Host-Zustand direkt liest, wird hier enttäuscht.

Installation und der erste lauffähige Server

Die Pakete liegen auf npm, RubyGems und PyPI. Für TypeScript sind @mcp-ui/server und @mcp-ui/client getrennt zu installieren; die Server-Seite arbeitet mit registerAppTool und registerAppResource aus @modelcontextprotocol/ext-apps/server zusammen. In Ruby heißt das Gem mcp_ui_server, in Python das Paket mcp-ui-server. Beide Nicht-TypeScript-Varianten sind laut README ausschließlich zum Erzeugen von UI-Ressourcen gedacht, ein Client-Renderer existiert dort nicht.

Ein minimaler Ablauf sieht so aus: Zuerst createUIResource mit uri, content vom Typ rawHtml und encoding auf text aufrufen. Das Ergebnis enthält resource.uri. Dann registerAppResource mit einem Namen, dieser URI und einem Callback, der contents mit dem Ressourcenobjekt zurückgibt. Schließlich registerAppTool mit inputSchema und dem Feld _meta.ui.resourceUri auf dieselbe URI. Der Tool-Handler selbst gibt weiterhin normalen Text zurück. Die UI hängt also nicht am Rückgabewert des Tools, sondern an den Metadaten seiner Registrierung. Wer das verwechselt, sucht den Fehler an der falschen Stelle.

Sicherheit ist hier eine Host-Aufgabe, keine SDK-Eigenschaft

Das README führt einen eigenen Abschnitt zu Sicherheit, ohne dass der vorliegende Auszug dessen Inhalt wiedergibt. Aus der Architektur lassen sich dennoch zwei Punkte ableiten. Erstens ist das sandbox-Prop von AppRenderer nicht optional in dem Sinne, dass es gefahrlos weggelassen werden könnte: Es trägt eine Proxy-URL, über die die eingebettete Seite kommuniziert. Wer diese Konfiguration falsch setzt, bekommt entweder eine tote UI oder eine, deren Nachrichten nicht korrekt gefiltert werden. Zweitens rendert HTMLResourceRenderer beliebiges HTML in einem iframe. Alles, was ein Server in htmlString schreibt, wird im Browser des Nutzers ausgeführt. Die Vertrauensgrenze verläuft damit entlang der Frage, welchen MCP-Servern ein Host überhaupt Ressourcen abnimmt.

Das SDK kann diese Entscheidung nicht abnehmen. Es liefert keine sichtbare Inhaltsrichtlinie, keine Allowlist für erlaubte URIs und keine Signaturprüfung für Ressourcen. Wer einen Host für fremde Server betreibt, muss diese Prüfungen selbst um die Rendering-Aufrufe herum bauen.

Plattform-Adapter und die Kosten der Host-Vielfalt

Das README erwähnt Plattform-Adapter, die zwischen host-spezifischen Implementierungen übersetzen sollen, damit dasselbe Widget in unterschiedlichen Hosts funktioniert. Der Auszug bricht mitten im Satz ab, deshalb lässt sich nicht sagen, welche Hosts konkret abgedeckt sind oder wie ein Adapter registriert wird. Wer auf diese Funktion setzt, sollte die Dokumentation auf mcpui.dev prüfen, bevor er sie einplant.

Klar ist die Richtung: Ein Widget soll nicht für jeden Host neu geschrieben werden. Der Preis dafür ist eine zusätzliche Übersetzungsschicht zwischen der UI und dem Host, und jede Schicht ist eine Stelle, an der Nachrichten verloren gehen oder sich in der Semantik verschieben können. Das ist ein bewusster Trade-off zugunsten von Portabilität. Für einen Host, der ausschließlich mit eigenen Servern spricht, bringt der Adapter keinen Nutzen und nur zusätzliche Angriffsfläche.

Wartung, Versionierung und Lizenz

Die Client-Pakete werden eigenständig versioniert, sichtbar an den Tags client/v7.1.1, client/v7.1.0 und client/v7.0.0. Der Sprung von 7.0.0 auf 7.1.0 im März 2026 und die beiden Folgeversionen im Mai 2026 deuten auf eine aktive Pflege der Client-Seite hin. Der letzte Push ins Repository datiert auf Juli 2026. Für Server-Pakete in TypeScript, Ruby und Python sind im vorliegenden Material keine Versions-Tags enthalten, sodass sich deren Release-Kadenz nicht beurteilen lässt. Wer eine dieser drei Server-Bibliotheken einplant, sollte die jeweilige Registry-Seite separat prüfen.

Lizenz ist Apache-2.0. Das erlaubt kommerzielle Nutzung und Modifikation, verlangt aber die Beibehaltung von Copyright- und Lizenzhinweisen sowie eine Kennzeichnung geänderter Dateien. Wer die Client-Pakete in ein eigenes Bundle einbettet und weitergibt, muss diese Hinweise mitführen. Das ist eine technische Einordnung, keine Rechtsberatung; für konkrete Weitergabeszenarien gehört die Prüfung zu einer Rechtsabteilung.

Wann ein anderer Ansatz die bessere Wahl ist

Die naheliegende Alternative ist, Tool-Ergebnisse gar nicht als HTML zu übertragen, sondern als strukturierte Daten und die Darstellung vollständig dem Host zu überlassen. Der Unterschied liegt nicht im Umfang, sondern in der Zuständigkeit. Bei mcp-ui bestimmt der Server, wie seine Ausgabe aussieht, und der Host rendert fremdes HTML in einem iframe. Bei einer host-eigenen Darstellung bestimmt der Host das Aussehen und konsumiert vom Server nur Daten. Das ist weniger flexibel für Server-Autoren, aber deutlich einfacher abzusichern, weil kein fremder Code im Browser läuft.

Ein zweiter Kontrast ergibt sich innerhalb des Projekts selbst. Apps SDK und mcp-ui haben laut README gemeinsam die MCP Apps Spezifikation beeinflusst, die UI-Auslieferung über das Protokoll standardisiert. Wenn ein Host bereits Apps SDK implementiert, ist die Frage nicht mehr mcp-ui gegen etwas anderes, sondern ob @mcp-ui/client als kompatibler Renderer über dieser Implementierung sinnvoll ist. Genau dafür wird AppRenderer im README positioniert.

Redaktionelles Fazit

Wer heute einen Host oder Server gegen die MCP Apps Spezifikation baut, findet in @mcp-ui/client und @mcp-ui/server die passenden Bausteine; bestehende MCP-UI-Integrationen sollten dagegen zunächst prüfen, ob UIResourceRenderer für sie weiterhin ausreicht, statt auf AppRenderer zu wechseln. Wer keinen MCP-Host betreibt und keine Tool-Ergebnisse als HTML darstellen will, braucht dieses SDK nicht. Vor dem Einstieg ist zu klären, ob die eigene Host-Umgebung bereits Apps SDK oder MCP Apps unterstützt, ob ein Proxy für das sandbox-Prop vorhanden ist und ob die Apache-2.0-Lizenz mit der geplanten Weitergabe der abgeleiteten Client-Bundles vereinbar ist.

Offizielle Quellen

1. License: Apache-2.0
2. MCP-UI-Org/mcp-ui on GitHub
3. Project website
4. README
5. Releases