AI SDKアプリケーションにMCPアプリを追加する

MCPアプリを使用すると、Model Context Protocol (MCP) ツールがプレーンテキストの代わりにインタラクティブなUIを返すことができます。モデルは通常のMCPツールを呼び出しますが、ツールはHTMLを含むui://リソースを指すことができ、アプリはそのHTMLをサンドボックス化されたiframeでレンダリングします。AI SDKは、@ai-sdk/mcpのヘルパー関数（MCPアプリサポートのアドバタイズ、モデル可視ツールのフィルタリング、ui://リソースの読み取り）と、iframeのレンダリングとメッセージのブリッジングを行う@ai-sdk/reactのコンポーネントを提供します。これにより、チャットUIにツールが生成したダッシュボード、フォーム、その他のインタラクティブビューを表示でき、信頼できないHTMLは分離されたままになります。

このガイドでは、以下の方法を学びます：MCPアップ機能を持つMCPサーバーへの接続；splitMCPAppToolsを使用してモデル可視のツールのみをモデルに渡す；readMCPAppResourceを使用してツールのui://リソースを読み取る；iframeからのアプリ可視ツール呼び出しを安全にプロキシする；Reactチャットでexperimental_MCPAppRendererを使用してアプリUIをレンダリングする。

始める前に、@ai-sdk/mcpと@ai-sdk/reactを含むaiパッケージ、MCP TypeScript SDK (@modelcontextprotocol/sdk) とプロバイダーパッケージ（@ai-sdk/openaiなど）、MCPアプリツールを公開するMCPサーバー、およびuseChatを使用するReactアプリ（例はNext.js App Routerを使用）が準備されていることを確認してください。

MCPアプリホストの動作フローは次のとおりです：MCPアプリクライアント機能を持つMCPサーバーに接続；サーバーのツールをリストし、可視性で分割；モデル可視のツールのみをstreamTextまたはgenerateTextに渡す；ツールパートにMCPアプリメタデータが含まれている場合、ui://リソースを読み取る；HTMLリソースをサンドボックス化されたiframeでレンダリング；許可されたiframeリクエスト（アプリ可視ツール呼び出しなど）をMCPサーバーにプロキシする。このガイドでは各ステップを順を追って構築します。

最初に、mcpAppClientCapabilitiesを使用してMCPクライアントを作成し、ホストがtext/html;profile=mcp-appリソースをレンダリングできることをアドバタイズします。次に、splitMCPAppToolsでツールリストを分割し、modelVisibleをstreamTextに渡します。モデルがアップバックされたツールを呼び出すと、MCPクライアントはツールUIにアプリメタデータを保持し、ReactレンダラーはツールパートにMCPアプリがあるかどうかを判断します。続いて、ブラウザホストに送信する前にreadMCPAppResourceを使用してツールのui://リソースを読み取ります。この関数はURIをチェックし、MCPアプリMIMEタイプを要求し、コンテンツをデコードしてHTMLとレンダリングメタデータ（コンテンツセキュリティポリシーや権限など）を返します。その後、アプリ可視ツール呼び出しをプロキシします。iframeはMCPサーバーに直接アクセスできないため、JSON-RPCメッセージをホストに送信し、ホストは要求されたツールがアプリ可視であることを確認してからMCPサーバーを呼び出します。最後に、ReactチャットUIでツールパートをexperimental_MCPAppRendererに渡します。このコンポーネントはリソースをロードし、サンドボックスブリッジを作成し、ツール入力と結果の通知をiframeに送信し、許可されたアプリリクエストをハンドラーを介して転送します。

ベストプラクティス：MCPアプリHTMLは信頼できないものとして扱い、サンドボックス化されたiframeでレンダリングする；アプリのみ可視のツールをモデルに渡さない；client.callToolを呼び出す前にサーバー側で各iframeリクエストを検証する；resourceUriでリソースをキャッシュして重複取得を避ける；各ツールのコンテンツと構造化コンテンツを単独でも有用に保ち、UIなしのテキストのみのホストでも動作するようにする；レスポンスまたはホストリクエストが完了したら短命のMCPクライアントを閉じる。

次のステップ：MCPアプリヘルパーリファレンス、MCPアプリレンダラーリファレンスを読み、基礎となるMCPツールの設定方法を学ぶ。