將MCP應用程序添加到您的AI SDK應用中

MCP應用程序允許模型上下文協議（MCP）工具返回交互式UI而非純文本。模型仍調用普通MCP工具，但工具可以指向包含HTML的ui://資源，應用程序在沙箱化iframe中渲染該HTML。AI SDK提供@ai-sdk/mcp幫助函數，用於廣告MCP應用程序支持、過濾模型可見的工具、讀取ui://資源，以及@ai-sdk/react組件用於渲染iframe並橋接消息。您的聊天界面可以顯示工具生成的儀表板、表單或其他交互式視圖，同時保持不受信任的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://資源；在沙箱化iframe中渲染HTML資源；代理允許的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，該組件會加載資源、創建沙箱橋接、發送工具輸入和結果通知，並通過處理程序轉發支持的應用程序請求。

最佳實踐包括：將MCP應用程序HTML視為不受信任內容，在沙箱化iframe中渲染；絕不將應用程序僅可見工具傳遞給模型，僅暴露modelVisible工具；在調用client.callTool前在服務器端驗證每個iframe請求；按resourceUri緩存資源以避免重複獲取；保持每個工具的內容和結構化內容獨立有用，以便純文本主機仍能工作；在響應或主機請求完成後關閉短生命週期MCP客户端。

下一步：閲讀MCP應用程序幫助函數參考、MCP應用程序渲染器參考，以及瞭解如何設置底層MCP工具。