MCP Apps

Interactive UI applications that render inside MCP hosts like Claude Desktop

TIP

For comprehensive API documentation, advanced patterns, and the full specification, visit the official MCP Apps documentation.

文本响应能表达的内容终究有限。有时用户需要与数据交互，而不仅仅是阅读数据。MCP Apps 让服务端能够返回交互式 HTML 界面（数据可视化、表单、仪表盘），并直接在聊天中渲染。

An Excalidraw MCP App drawing a sequence diagram inside a Claude conversation — Excalidraw MCP App, running in Claude

为什么不直接构建一个 Web 应用？

你可以构建一个独立的 Web 应用，然后给用户发送一个链接。然而，MCP Apps 提供了以下独立页面无法比拟的关键优势：

上下文保持。 应用就存在于对话之中。用户无需切换标签页、不会丢失当前进度，也不必回想那个仪表盘究竟在哪个聊天会话里。界面就在那里，与引出它的讨论并排呈现。
双向数据流。 你的应用可以调用 MCP 服务端上的任何工具，宿主也可以向你的应用推送最新结果。独立的 Web 应用则需要自己的 API、身份验证和状态管理。MCP Apps 通过现有的 MCP 模式即可获得这些能力。
与宿主能力集成。应用可以将操作委托给宿主，宿主随后可以调用用户已经连接的能力和工具（需经用户同意）。应用无需各自实现和维护直接集成（例如电子邮件服务商），而是可以请求一个结果（例如"安排这次会议"），由宿主通过用户已有的已连接能力进行路由。
安全保障。 MCP Apps 运行在由宿主控制的沙箱 iframe 中。它们无法访问父页面、窃取 cookie 或逃逸其容器。这意味着宿主可以安全地渲染第三方应用，而无需完全信任服务端作者。

如果你的用例无法从这些特性中获益，那么普通的 Web 应用可能更简单。但如果你希望与基于 LLM 的对话紧密集成，MCP Apps 则是更好的工具。

MCP Apps 的工作原理

传统的 MCP 工具返回文本、图像、资源或结构化数据，由宿主作为对话的一部分进行展示。MCP Apps 扩展了这一模式，允许工具在其工具描述中声明对交互式 UI 的引用，由宿主就地渲染。

核心模式结合了两个 MCP 原语：一个在其描述中声明 UI 资源的工具，加上一个将数据渲染为交互式 HTML 界面的 UI 资源。

当大语言模型（LLM）决定调用一个支持 MCP Apps 的工具时，会发生以下过程：

UI 预加载：工具描述中包含一个 _meta.ui.resourceUri 字段，指向一个 ui:// 资源。宿主甚至可以在工具被调用之前就预加载该资源，从而实现诸如将工具输入流式传输到应用等功能。
资源获取：宿主从服务端获取 UI 资源。该资源包含一个 HTML 页面，为简便起见通常与其 JavaScript 和 CSS 打包在一起。应用也可以从 _meta.ui.csp 中指定的来源加载外部脚本和资源。
沙箱渲染：Web 宿主通常会在对话内的沙箱 iframe 中渲染该 HTML。沙箱限制了应用对父页面的访问，从而确保安全。资源的 _meta.ui 对象可以包含 permissions 以请求额外能力（例如麦克风、摄像头），以及 csp 以控制应用可以从哪些外部来源加载资源。
双向通信：应用与宿主通过一套 JSON-RPC 协议进行通信，该协议构成了 MCP 的自身方言。部分请求和通知与核心 MCP 协议共享（例如 tools/call），部分与之相似（例如 ui/initialize），而大多数则是新增的，带有 ui/ 方法名前缀。应用可以请求工具调用、发送消息、更新模型上下文，并接收来自宿主的数据。

sequenceDiagram
    participant User
    participant Agent
    participant App as MCP App iframe
    participant Server as MCP Server

    User->>Agent: "show me analytics"
    Note over User,App: Interactive app rendered in chat
    Agent->>Server: tools/call
    Server-->>Agent: tool input/result
    Agent-->>App: tool result pushed to app
    User->>App: user interacts
    App->>Agent: tools/call request
    Agent->>Server: tools/call (forwarded)
    Server-->>Agent: fresh data
    Agent-->>App: fresh data
    Note over User,App: App updates with new data
    App-->>Agent: context update

应用与宿主保持隔离，但仍可通过安全的 postMessage 通道调用 MCP 工具。

何时使用 MCP Apps

当你的用例涉及以下情况时，MCP Apps 是很好的选择：

探索复杂数据。 用户问"按地区展示我的销售额"。文本响应可能会列出数字，但 MCP App 可以渲染一张交互式地图，用户点击地区即可下钻、悬停查看详情、在不同指标之间切换，而无需额外的提示。

配置大量选项。 设置一次部署涉及数十个相互依赖的选择。与其来回对话（"哪个地区？""什么实例规格？""启用自动扩缩容吗？"），MCP App 可以呈现一个表单，让用户一次性看到所有选项，并带有校验和默认值。

查看富媒体。 当用户要求审阅 PDF、查看 3D 模型或预览生成的图像时，纯文本描述力有不逮。MCP App 将实际的查看器（平移、缩放、旋转）直接嵌入对话中。

实时监控。 展示实时指标、日志或系统状态的仪表盘需要持续更新。MCP App 维持持久连接，在数据变化时更新显示，无需用户询问“现在状态如何？”

多步骤工作流。 审批费用报告、审阅代码变更或分诊问题都涉及逐项检查。MCP App 提供导航控件、操作按钮以及跨交互持久存在的状态。

安全模型

MCP App 运行在沙箱化的 iframe 中，与宿主应用实现强隔离。该沙箱阻止你的应用访问父窗口的 DOM、读取宿主的 cookie 或本地存储、导航父页面，或在父上下文中执行脚本。

你的应用与宿主之间的所有通信都通过 postMessage API 进行。宿主控制你的应用可以访问哪些能力。例如，宿主可能限制应用可以调用哪些工具，或禁用 sendOpenLink 能力。

该沙箱旨在防止应用逃逸以访问宿主或用户数据。

框架支持

MCP App 使用自己的一套 MCP 方言，与核心协议一样构建在 JSON-RPC 之上。部分消息与常规 MCP 共享（例如 tools/call），另一些则是应用特有的（例如 ui/initialize）。传输方式是 postMessage，而非 stdio 或 HTTP。由于全部基于标准 Web 原语，你可以使用任意框架，也可以完全不用框架。

来自 @modelcontextprotocol/ext-apps 的 App 类是一个便捷封装，而非强制要求。如果你希望避免依赖或需要更精细的控制，可以直接实现 postMessage 协议。

examples 目录包含 React、Vue、Svelte、Preact、Solid 和 vanilla JavaScript 的入门模板。这些模板演示了各框架体系的推荐模式，但它们是示例而非要求。你可以选择最适合自己用例的方案。

客户端支持

NOTE

MCP Apps 是核心 MCP 规范的扩展。宿主支持因客户端而异。

MCP Apps 目前由 Claude、Claude Desktop、VS Code GitHub Copilot、Microsoft 365 Copilot、Goose、Postman、MCPJam 和 Archestra.AI 支持。请参阅客户端矩阵以了解各客户端扩展支持的完整列表。

如果你正在构建 MCP 客户端并希望支持 MCP Apps，有两种选择：

使用框架：@mcp-ui/client 包提供了 React 组件，用于在你的宿主应用中渲染 MCP App 视图并与之交互。使用详情请参阅 MCP-UI 文档。
基于 AppBridge 构建：SDK 包含一个 App Bridge 模块，负责在沙箱化 iframe 中渲染应用、消息传递、工具调用代理以及安全策略执行。basic-host 示例展示了如何集成它。

实现细节请参阅 API 文档。

示例

ext-apps 仓库包含可直接运行的示例，演示了不同的用例：

3D 与可视化： map-server （CesiumJS 地球仪）、 threejs-server （Three.js 场景）、 shadertoy-server （着色器效果）
数据探索： cohort-heatmap-server、 customer-segmentation-server、 wiki-explorer-server
业务应用： scenario-modeler-server、 budget-allocator-server
媒体： pdf-server、 video-resource-server、 sheet-music-server、 say-server （文本转语音）
实用工具： qr-server、 system-monitor-server、 transcript-server （语音转文本）
入门模板： React、 Vue、 Svelte、 Preact、 Solid、 vanilla JavaScript

要开始构建你自己的 MCP App，请参阅构建指南。