MCP Apps 实战：给 Agent 工具加交互界面，也要守住能力协商、最小权限与文本降级

承接 协议升级深度实践MCP无状态化迁移清单网关、任务与鉴权 ·协议升级后的验收深度实践 MCP迁移实战用官方 Conformance Suite 给 Client/Server 加回归门禁调研日期2026-08-03本文目标将 MCP Apps 作为一个可协商、可降级、可审查的交互层接入 MCP Server而不是让聊天里的 iframe 绕开工具权限、网络限制或人工确认。MCP 工具返回文本与结构化数据已经能覆盖大量 Agent 场景但它不擅长审批表单、实时状态、图表和复杂选择。MCP Apps 为这类场景定义了标准路径Server 声明ui://资源Host 在沙箱 iframe 中渲染 View并经由 Host 把 UI 的交互继续纳入 MCP 的通信与审计路径。MCP Apps 的2026-01-26规范已标为稳定而 2026 年 MCP 的扩展化方向又使它成为值得优先评估的能力。官方规范与项目文档都强调这是一项可选扩展Host 支持度不同不能假设“接了 MCP 就一定能渲染 UI”。因此最可靠的实现目标不是“让每个工具都有一个漂亮界面”而是即使 UI 不存在、加载失败或被 Host 拒绝工具仍以安全且有意义的文本契约工作而当 UI 可用时它也只拥有完成该交互所需的最小能力。适用前提你维护一个可在隔离环境启动的 MCP Server并能同时测试至少一个目标 Host 和不支持 MCP Apps 的纯文本路径。本文不假设任意生产 Host 都支持该扩展上线前应按目标客户端、SDK 与规范版本逐一核验。一、先看清三方边界Server、Host 与 View 各做什么MCP Apps 的关键不在于“把网页塞进聊天框”而在于保持下面三条通信边界Agent / 模型 │ 选择工具 ▼ Host聊天客户端、能力协商、iframe 沙箱、审计代理 │ MCP tools/call、resources/read ▼ MCP Server工具、ui:// 资源、业务授权 Host ⇄ postMessage / JSON-RPC ⇄ Viewiframe 中的交互界面组件主要责任不应承担的责任MCP Server声明工具与 UI 资源、执行业务授权、返回文本与结构化数据假定浏览器存在或把授权判断下放给前端Host协商扩展能力、获取资源、用沙箱 iframe 渲染并代理通信把任何 UI 按钮默认视为已获用户授权View展示数据、收集受限输入、通过 Host 请求允许的工具直接连接其他 Server、持有高权限凭据或取代 Server 鉴权规范将 UI 资源与普通资源区分为ui://URI并要求初始 HTML 资源使用text/html;profilemcp-app。View 与 Host 的双向通信使用 JSON-RPC 基础协议这意味着“刷新”“分页”“提交表单”等界面交互不必暴露成模型上下文里的新工具但也不意味着它们脱离审计与权限边界。二、先做能力协商与文本降级再谈 UI 体验MCP Apps 是渐进增强progressive enhancement不是前置依赖。Server 应先判断 Host 是否声明了相应 UI 能力支持时注册带 UI 元数据的工具不支持时仍提供同一业务结果的文本版本。无论哪条路径工具都要返回有意义的content不能只把关键数据藏在 iframe 里。Host 状态Server 行为用户可见结果失败信号已协商 MCP Apps关联ui://模板并返回文本摘要和结构化数据可交互的仪表盘/表单同时保留可读摘要UI 存在但文本结果为空无法审计或降级不支持或未协商不注册 UI 元数据走普通工具结果可读文本、JSON 或链接说明工具因缺少 iframe 直接失败UI 资源读取失败回退到文本结果并记录受控诊断用户仍能完成只读判断或请求人工处理业务结论只能从前端看见UI 需发起动作仅暴露经过定义的 app-only 工具经 Host 转发明确的动作、理由与确认路径View 直接调用未声明或跨 Server 的能力这条降级策略还能避免一个常见兼容性陷阱官方项目明确提示 Host 支持会变化。把“目标 Host 已测试的 UI 版本”和“纯文本回退仍通过”都放入发布验收才不会因一个客户端升级而让核心工具失效。三、用两类工具划出模型和界面的最小契约规范允许在工具的_meta.ui中关联 UI 资源并通过visibility区分模型和 App 能否调用。下面是协议级契约示意用于说明边界实际注册 API 应以已固定版本的modelcontextprotocol/ext-appsSDK 为准。{ name: show_change_risk, description: 返回一次变更风险评估的文本摘要和交互式详情, inputSchema: { type: object, properties: { changeId: { type: string } } }, _meta: { ui: { resourceUri: ui://risk-console/change-risk, visibility: [model, app] } } }上面的业务工具可被模型选择也能让 UI 获得相同 Server 连接内的结果。对刷新、页码切换或临时表单状态这类不该污染模型上下文的动作使用 app-only 工具{ name: refresh_change_risk, description: 仅供风险面板刷新其已展示的数据, inputSchema: { type: object }, _meta: { ui: { resourceUri: ui://risk-console/change-risk, visibility: [app] } } }visibility: [app]不会让模型看见或调用这个工具且 app-only 工具只能由同一 Server 连接中的 App 使用。它适合低风险、界面专属的读取和刷新它不是隐私标签也不是把危险操作藏起来的方式。只要动作会改变外部系统、权限或数据就仍需要 Server 侧授权、明确的输入校验以及符合团队政策的用户确认或人工审批。新实现应使用嵌套的_meta.ui.resourceUri结构不要从已弃用的扁平ui/resourceUri别名开始。模板和数据也要拆开模板是可审查、可缓存的静态资源工具结果才承载每次调用的动态数据。四、把 iframe 当作隔离边界而不是信任边界MCP Apps 的规范要求 Host 以沙箱 iframe 渲染 HTML并允许资源通过元数据声明 CSP。最小网络策略应从“没有外连”开始规范中省略或留空connectDomains的含义是没有外部连接只有确实需要的 API 或 WebSocket 域名才逐项加入。{ uri: ui://risk-console/change-risk, mimeType: text/html;profilemcp-app, _meta: { ui: { csp: { connectDomains: [https://risk-api.example.internal], resourceDomains: [https://static.example.internal] }, prefersBorder: true } } }示例中的域名只是占位形态生产配置必须替换为团队实际受控的精确来源不要使用*、临时 CDN 通配或未经审核的第三方埋点。还应明确以下四条原则资源先审查再渲染。UI 模板应进入代码审查、版本固定和安全扫描Host 可以在工具运行前预取或审查资源并不代表团队不必审查其供应链。前端不持久化高权限凭据。View 需要的数据应由 Server 依据当前请求和身份提供不能把服务 Token、OAuth refresh token 或客户数据打进 HTML。按钮不是审批。“确认部署”“提交修改”按钮只能发起一个受控工具调用真正允许或拒绝应发生在 Server/Host 的授权与审批链上。内容与指令分离。从工具结果呈现的外部文本、图表标签或链接都可能是不可信内容不能反向改变 UI 能调用的工具白名单。五、用一个只读原型验证端到端再增加写操作官方ext-apps仓库提供了basic-host和多个示例。要快速检查本地渲染链路可在隔离环境运行其参考实现git clone https://github.com/modelcontextprotocol/ext-apps.git cd ext-apps npm install npm start然后先接一个只读工具例如变更风险摘要、构建状态或资产清单。首个版本不需要“提交”按钮它只需证明资源发现、Host 渲染、文本回退和错误处理都按预期工作。下面这张验收矩阵比“界面是否好看”更重要场景期望结果失败信号支持 UI 的目标 Hostui://资源在沙箱中渲染工具仍返回文本摘要UI 成为唯一数据载体不支持 UI 的 Host不带 UI 元数据的工具照常返回可读结果因无 iframe 而报错或空结果CSP 未列出的外部请求被阻止并产生受控诊断模板可随意连接任意域名app-only 刷新工具不进入模型的工具列表只能在同一 App 会话使用模型能调用隐藏工具或跨 Server 调用成功恶意/异常工具数据文本和 UI 都把它当数据不扩展权限页面内容可诱导自动执行高风险动作UI 资源版本升级通过固定 SDK/Host 组合验证并可回滚只更新前端模板未重测协议与降级路径确定只读原型稳定后再把一个可逆的动作做成 app-only 工具并让 Server 对每次调用验证身份、对象范围、参数和审计字段。涉及提交、删除、转账、修改生产配置等不可逆操作时UI 只能改善信息呈现不能替代现有的人审、权限检查与变更记录。六、把 MCP Apps 纳入同一套协议与供应链门禁上一节的 UI 规范并不替代核心 MCP 的升级与 conformance。建议将发布检查拆成三层层次最小检查不能证明什么MCP 协议层当前 SDK/传输组合通过项目的协议测试与回归门禁UI 模板的 CSP、交互和业务授权正确App 资源层ui://URI、MIME type、资源内容、能力协商与文本回退都被测试业务动作是否按组织流程获批业务动作层参数校验、最小权限、审计关联、人工确认与回滚演练其他 Host 是否同样支持该 UI每次升级modelcontextprotocol/ext-apps、核心 SDK、Host 或 UI 打包链时都应重新运行这三层检查。不要只因某个演示 Host 成功显示面板就宣布生产客户端、网关和认证路径已经兼容。七、六个常见误区1把 MCP Apps 当成所有 Host 的默认能力它是可选扩展Host 兼容度需要实际验证。文本回退不是“旧客户端兼容补丁”而是协议设计的一部分。2只返回 iframe不返回文本结果这样会让无 UI Host、审计系统和辅助工具失去核心信息也会让故障时无法判断工具是否已成功。3将 app-only 误解为保密或高权限通道它只控制工具对模型/App 的可见性Server 仍要逐次鉴权、校验参数并记录动作。4放宽 CSP 来解决加载失败宽泛的 CDN 或未固定的远程脚本会把调试便利变成供应链与数据外传风险。应先找出真正需要的精确来源。5让 UI 按钮直接代表用户同意界面点击只是一个输入事件。高影响操作仍需要服务端确认当前身份、目标、范围和审批状态。6将 UI 测试与协议升级测试割裂传输、能力协商和资源发现的变化都可能破坏界面。MCP Apps 应和核心 MCP 回归一起被验证。结语MCP Apps 最有价值的地方是把图表、表单和复杂状态从“每个聊天客户端各做一套”变成可协商的协议扩展但只有把 UI 当成渐进增强的受限视图它才不会变成新的权限旁路。从一个只读面板开始先让支持 UI 的 Host 能渲染确认不支持时仍返回完整文本再测试 CSP、app-only 工具与审计关联。等这条最小闭环被证明稳定后才逐一增加可逆交互与需要人工确认的业务动作。这样丰富界面提升的是 Agent 的可用性而不是它的越权能力。来源与延伸阅读MCP Apps 官方仓库与 SDKmodelcontextprotocol/ext-apps、参考 Host、示例、安装与兼容性提示。SEP-1865MCP Apps 交互式 UI 规范ui://资源、工具元数据、可见性、iframe 沙箱、CSP 与能力协商。MCP Apps Overview渐进增强、Server/Host/View 三方架构和 app-only 工具的实践说明。MCP 2026-07-28 修订说明协议无状态化与扩展机制的背景实际部署仍应以当前正式规范和 SDK 版本为准。协议升级深度实践MCP无状态化迁移清单网关、任务与鉴权 先厘清传输、状态、鉴权与网关迁移。协议升级后的验收深度实践 MCP迁移实战用官方 Conformance Suite 给 Client/Server 加回归门禁将协议一致性测试固定进 CI避免只凭一次连接成功判断兼容。