mcp-ui を採用する前に読む、MCP Apps 準拠 SDK の実装と境界

mcp-ui が埋める、MCP のテキスト応答と画面のあいだの隙間

MCP のツール呼び出しは本質的にテキストのやり取りである。サーバーが結果を返し、ホストがそれを表示する。表やフォームやボタンが必要な場面でも、返ってくるのは文字列だ。mcp-ui はこの隙間を、ツールと UI リソースを紐づけることで埋める。README によれば、MCP Apps パターンでは _meta.ui.resourceUri がツールとその UI を結びつけ、ホストは resources/read で UI を取得して AppRenderer で描画する。対象読者は、MCP サーバーにリッチな操作画面を持たせたいサーバー実装者と、それを表示するホストの開発者である。

_meta.ui.resourceUri を起点にしたデータの流れ

仕組みは単純で、追いやすい。まず createUIResource で ui://my-server/widget のような URI を持つリソースを作る。次に registerAppResource でその URI を resources/read に応答させ、registerAppTool の _meta に { ui: { resourceUri: widgetUI.resource.uri } } を書いてツールと結びつける。ホスト側は _meta.ui.resourceUri を検出し、リソースを取得し、AppRenderer に client と toolName を渡して描画する。UIResource の実体は type: 'resource' のオブジェクトで、uri、mimeType、そして text か blob のいずれかを持つ。mimeType は MCP Apps 標準の text/html;profile=mcp-app が使われる。blob は Base64 エンコードされた HTML である点に注意したい。

導入はパッケージ追加から始まるが、サンドボックスを自分で用意する必要がある

README が示す経路は @mcp-ui/server と @mcp-ui/client の導入から始まる。サーバー側は createUIResource、registerAppResource、registerAppTool の三点セットで UI 付きツールを登録する。クライアント側は AppRenderer に client、toolName、sandbox、toolInput、toolResult、onOpenLink、onMessage を渡す。ここで見落としやすいのは sandbox プロパティで、README は「Sandbox configuration with proxy URL」とだけ説明しており、その URL をどう用意するかは記述がない。HTML は内部の HTMLResourceRenderer が iframe 内に表示するため、プロキシの運用はホスト側の責任になる。なお Ruby の mcp_ui_server と Python の mcp-ui-server は UI リソースの生成のみを担い、レンダリングは TypeScript 側の役割である。

UIResourceRenderer は残っているが、位置づけはレガシーである

同じ @mcp-ui/client に UIResourceRenderer という別のコンポーネントがある。こちらはツール応答にリソースを埋め込む従来型のホスト向けで、resource と onUIAction を受け取る。Web Component として <ui-resource-renderer> を使う書き方も README に載っている。両者は用途が異なる。AppRenderer は client 経由でリソースを自動取得し、UIResourceRenderer は渡された resource をそのまま描画する。既存ホストを MCP Apps へ移す場合、この二つが同一パッケージに同居していることが移行の判断を曖昧にする。README は AppRenderer を推奨と明記しているが、レガシー側の削除時期には触れていない。

UI からの操作は onUIAction と onMessage に集約される

UI スニペットは静的な表示で終わらない。ボタンクリックなどを起点にエージェントへ働きかける必要がある。mcp-ui では、UI から送られるイベントをホスト側で受け取る形をとる。レガシー API では onUIAction が tool、prompt、link、notify、intent の各アクションを処理し、MCP Apps 側では onMessage と onOpenLink がその窓口になる。つまり UI とエージェントのあいだの権限は、すべてホストのコールバック実装に依存する。何を許可し何を拒否するかを決めるのは SDK ではなくホストであり、ここを空のままにすると iframe 内の HTML が送るイベントを無条件に通すことになる。

確認できない部分と、向かないケース

README は「fully compliant with the MCP Apps specification and ready for production use」と述べているが、これはプロジェクト自身の主張であり、本稿で動作を検証したわけではない。サンドボックスの実装詳細、プロキシ URL の仕様、MCP Apps 仕様との差分の網羅性は、この資料からは確認できない。向かないのは、UI を伴わない純粋なデータ処理ツールだけを提供するサーバーである。iframe とサンドボックスを挟む分、テキスト応答だけのツールより構成要素が増える。また、ホストが MCP Apps の _meta.ui.resourceUri を解釈しない場合、登録した UI は単に取得されない。ホスト側の対応状況が導入の成否を決める。

Apps SDK との関係と、仕様が外部にあるという制約

README は、mcp-ui が MCP 上の対話的 UI という概念を先に打ち出し、そのパターンが MCP Apps 仕様の標準化に影響を与えたと説明している。同時に Apps SDK にも言及し、両者が仕様形成に関わったとする。注目すべきは、標準が modelcontextprotocol/ext-apps という別リポジトリに置かれている点だ。mcp-ui はその実装側であり、仕様変更は mcp-ui の外で決まる。registerAppTool と registerAppResource が @modelcontextprotocol/ext-apps/server から来ているのも、役割分担がパッケージ境界に表れている。仕様に追随するコストは mcp-ui 側ではなく、依存する ext-apps 側の更新に左右される。

ライセンスと更新の追い方

ライセンスは Apache-2.0 で、特許条項と変更点の明示が含まれる。派生物に何を表示すべきかなど具体的な義務は、採用前に LICENSE 本文を確認されたい。ここで法的助言はできない。更新面では、client パッケージが v7.1.1（2026-05-09）、v7.1.0（2026-05-01）、v7.0.0（2026-03-12）と短期間で並んでおり、メジャー更新が約二か月で入っている。client のバージョンを固定し、@modelcontextprotocol/ext-apps との組み合わせを lockfile で管理するのが現実的である。サーバー側の @mcp-ui/server、Ruby、Python の各パッケージは別バージョン体系なので、混同しないよう注意したい。

編集部の結論

MCP Apps 仕様に沿ってホスト側を実装するチーム、特に @mcp-ui/client の AppRenderer でサンドボックス付きのツール UI を描画したい場合に向く。逆に、ツール応答に UI を埋め込む従来型のホストを維持しているなら、UIResourceRenderer を使う必要があり、両 API の混在は混乱を招く。採用前に確認すべきは、sandbox に渡すプロキシ URL の運用方法と、createUIResource が返す mimeType が text/html;profile=mcp-app になっているかどうかである。

公式情報源

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