MCP Apps宿主沙箱实现iframe sandbox属性与权限配置完整指南【免费下载链接】ext-appsOfficial repo for spec SDK of MCP Apps protocol - standard for UIs embedded AI chatbots, served by MCP servers项目地址: https://gitcode.com/GitHub_Trending/ex/ext-appsMCP Apps 宿主沙箱Host Sandbox是 MCP Apps 协议安全体系的核心它通过iframe sandbox 属性、跨源双层 iframe 架构与权限白名单把不可信的应用 UI 安全地嵌入 AI 聊天界面。本文带你读懂这套沙箱机制的设计原理、sandbox 属性配置方式与权限allow 属性、CSP设置方法并附完整的关键源码文件路径。什么是 MCP Apps嵌入 AI 聊天窗的交互界面MCP Apps 是 模型上下文协议MCP 的一个扩展协议让 MCP 服务器不仅返回文本还能返回可交互的 UI 视图View——比如折线图、地图、PDF 查看器。这些视图通过 iframe 渲染在 Claude Desktop 等宿主Host的聊天流中本仓库是 MCP Apps 协议规范与官方 SDK 的所在地包含协议规范specification/2026-01-26/apps.mdx、TypeScript 运行时src/以及可运行的示例宿主examples/basic-host/。宿主沙箱架构为什么是“双层 iframe”设计规范明确要求当宿主是网页时必须用一层“Sandbox Proxy沙箱代理”包裹 View且宿主的源origin与沙箱的源必须不同。结构如下宿主页面 (Host) └─ 外层 iframeSandbox Proxy不同源如 localhost:8081/sandbox.html └─ 内层 iframeView渲染服务器返回的 HTMLsandbox 受限这样设计的原因很直接跨源隔离。即使应用 HTML 被恶意篡改它也拿不到宿主页面的 cookie、DOM 和本地存储而内外两层 iframe 因跨源无法直接通信就由沙箱代理充当双向消息中继只转发合法消息。上图是官方示例宿主 examples/basic-host/ 的运行界面下方即 View 渲染的沙箱区域。核心实现文件沙箱代理逻辑examples/basic-host/src/sandbox.ts宿主装载与握手逻辑examples/basic-host/src/implementation.ts代理页面壳examples/basic-host/sandbox.htmlsandbox 属性怎么配allow-scripts 与 allow-same-origin 的取舍浏览器给 iframe 提供的sandbox属性是一组开关白名单写了什么才允许什么默认全部禁用。规范对沙箱代理的要求见 specification/2026-01-26/apps.mdx 的 Sandbox proxy 章节要求说明必须允许allow-scriptsView 的 JavaScript 需要运行必须允许allow-same-origin沙箱页面本身需要正常源身份绝不允许allow-top-navigation等防止页面跳转逃逸出 iframe内层 iframe 可被覆盖宿主可通过sendSandboxResourceReady的sandbox参数定制更严策略官方示例中宿主在装载沙箱代理时这样设置examples/basic-host/src/implementation.tsiframe.setAttribute(sandbox, allow-scripts allow-same-origin allow-forms);而沙箱代理在创建内层 iframe真正渲染 View 的那一层时同样设置基础策略examples/basic-host/src/sandbox.tsinner.setAttribute(sandbox, allow-scripts allow-same-origin allow-forms); // allow 属性在收到 sandbox-resource-ready 通知后再按应用声明的权限设置值得注意的是sandbox-resource-ready消息里带有一个可选的sandbox字段内层 iframe sandbox 属性的可选覆盖值见 src/generated/schema.ts宿主可以据此为每个应用收紧或放开权限。内置安全自检验证沙箱真的生效沙箱代理启动时会主动做一次逃逸测试尝试访问window.top。在正确的沙箱下这会抛出SecurityError如果访问成功说明配置失守并立即终止examples/basic-host/src/sandbox.ts。这是验证沙箱配置是否安全的一个极简技巧写宿主时值得借鉴。权限配置allow 属性与设备权限白名单除sandbox外iframe 还有第二套机制——Permission Policy 的allow属性用于声明摄像头、麦克风等设备权限。MCP Apps 约定应用在资源元数据_meta.ui.permissions中声明所需权限宿主/沙箱再用 SDK 提供的buildAllowAttribute工具函数转换成 allow 字符串src/app-bridge.ts应用声明的权限生成的 allow 指令cameracameramicrophonemicrophonegeolocationgeolocationclipboardWriteclipboard-write沙箱代理收到sandbox-resource-ready通知后先按声明设置allow属性再把 HTML 用document.write写入内层 iframeexamples/basic-host/src/sandbox.ts。测试用例可参考 src/app-bridge.test.ts。网络权限的另一半CSP 配置沙箱只管行为网络请求则由Content Security PolicyCSP管控。MCP Apps 的 HTML 没有同源服务器所以应用必须在资源元数据_meta.ui.csp中声明全部允许的域名docs/csp-cors.mdconnectDomainsfetch / XHR / WebSocket 可访问的域名含开发时的 localhostresourceDomains脚本、样式、图片、字体来源未声明时沙箱会套用严格默认值如object-src none、frame-src none官方示例中宿主把 CSP 通过 URL 查询参数传给沙箱页面再由服务器以HTTP 响应头下发响应头比meta标签更难被篡改见 examples/basic-host/src/implementation.ts。下面这个地图应用就依赖connectDomainsresourceDomains从跨源加载瓦片与脚本完整示例见 examples/map-server/ 与 examples/sheet-music-server/。一次完整的沙箱握手流程把上面各环节串起来宿主打开一个 MCP App 的完整时序为宿主在不同源URL 上加载沙箱代理 iframe带上 CSP 参数沙箱代理自检通过后向宿主发送ui/notifications/sandbox-proxy-ready宿主读取 View 的 HTML 资源通过ui/notifications/sandbox-resource-ready发送 HTML、CSP 与权限声明沙箱代理设置allow属性并把 HTML 写入内层 iframe此后沙箱代理只做消息中继宿主 ↔ 沙箱 ↔ View逐跳校验 originView 完成ui/initialize握手后宿主才下发工具调用参数。相关 SDK 方法sendSandboxResourceReady与onsandboxreadysrc/app-bridge.ts。关键文件速查 想了解什么看哪里协议规范与沙箱代理要求specification/2026-01-26/apps.mdx沙箱代理完整实现examples/basic-host/src/sandbox.ts宿主加载沙箱与消息桥接examples/basic-host/src/implementation.ts权限 allow 属性构建工具src/app-bridge.tsCSP 与 CORS 配置指南docs/csp-cors.md从零构建第一个 MCP Appdocs/quickstart.md沙箱安全测试tests/e2e/security.spec.ts一句话总结MCP Apps 宿主沙箱 跨源双层 iframe隔离sandbox 属性白名单能力收敛allow/CSP 双通道授权按需放行三者叠加让把服务器 HTML 直接渲染进聊天窗口这件事真正变得安全可控。【免费下载链接】ext-appsOfficial repo for spec SDK of MCP Apps protocol - standard for UIs embedded AI chatbots, served by MCP servers项目地址: https://gitcode.com/GitHub_Trending/ex/ext-apps创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
MCP Apps宿主沙箱实现：iframe sandbox属性与权限配置完整指南
MCP Apps宿主沙箱实现iframe sandbox属性与权限配置完整指南【免费下载链接】ext-appsOfficial repo for spec SDK of MCP Apps protocol - standard for UIs embedded AI chatbots, served by MCP servers项目地址: https://gitcode.com/GitHub_Trending/ex/ext-appsMCP Apps 宿主沙箱Host Sandbox是 MCP Apps 协议安全体系的核心它通过iframe sandbox 属性、跨源双层 iframe 架构与权限白名单把不可信的应用 UI 安全地嵌入 AI 聊天界面。本文带你读懂这套沙箱机制的设计原理、sandbox 属性配置方式与权限allow 属性、CSP设置方法并附完整的关键源码文件路径。什么是 MCP Apps嵌入 AI 聊天窗的交互界面MCP Apps 是 模型上下文协议MCP 的一个扩展协议让 MCP 服务器不仅返回文本还能返回可交互的 UI 视图View——比如折线图、地图、PDF 查看器。这些视图通过 iframe 渲染在 Claude Desktop 等宿主Host的聊天流中本仓库是 MCP Apps 协议规范与官方 SDK 的所在地包含协议规范specification/2026-01-26/apps.mdx、TypeScript 运行时src/以及可运行的示例宿主examples/basic-host/。宿主沙箱架构为什么是“双层 iframe”设计规范明确要求当宿主是网页时必须用一层“Sandbox Proxy沙箱代理”包裹 View且宿主的源origin与沙箱的源必须不同。结构如下宿主页面 (Host) └─ 外层 iframeSandbox Proxy不同源如 localhost:8081/sandbox.html └─ 内层 iframeView渲染服务器返回的 HTMLsandbox 受限这样设计的原因很直接跨源隔离。即使应用 HTML 被恶意篡改它也拿不到宿主页面的 cookie、DOM 和本地存储而内外两层 iframe 因跨源无法直接通信就由沙箱代理充当双向消息中继只转发合法消息。上图是官方示例宿主 examples/basic-host/ 的运行界面下方即 View 渲染的沙箱区域。核心实现文件沙箱代理逻辑examples/basic-host/src/sandbox.ts宿主装载与握手逻辑examples/basic-host/src/implementation.ts代理页面壳examples/basic-host/sandbox.htmlsandbox 属性怎么配allow-scripts 与 allow-same-origin 的取舍浏览器给 iframe 提供的sandbox属性是一组开关白名单写了什么才允许什么默认全部禁用。规范对沙箱代理的要求见 specification/2026-01-26/apps.mdx 的 Sandbox proxy 章节要求说明必须允许allow-scriptsView 的 JavaScript 需要运行必须允许allow-same-origin沙箱页面本身需要正常源身份绝不允许allow-top-navigation等防止页面跳转逃逸出 iframe内层 iframe 可被覆盖宿主可通过sendSandboxResourceReady的sandbox参数定制更严策略官方示例中宿主在装载沙箱代理时这样设置examples/basic-host/src/implementation.tsiframe.setAttribute(sandbox, allow-scripts allow-same-origin allow-forms);而沙箱代理在创建内层 iframe真正渲染 View 的那一层时同样设置基础策略examples/basic-host/src/sandbox.tsinner.setAttribute(sandbox, allow-scripts allow-same-origin allow-forms); // allow 属性在收到 sandbox-resource-ready 通知后再按应用声明的权限设置值得注意的是sandbox-resource-ready消息里带有一个可选的sandbox字段内层 iframe sandbox 属性的可选覆盖值见 src/generated/schema.ts宿主可以据此为每个应用收紧或放开权限。内置安全自检验证沙箱真的生效沙箱代理启动时会主动做一次逃逸测试尝试访问window.top。在正确的沙箱下这会抛出SecurityError如果访问成功说明配置失守并立即终止examples/basic-host/src/sandbox.ts。这是验证沙箱配置是否安全的一个极简技巧写宿主时值得借鉴。权限配置allow 属性与设备权限白名单除sandbox外iframe 还有第二套机制——Permission Policy 的allow属性用于声明摄像头、麦克风等设备权限。MCP Apps 约定应用在资源元数据_meta.ui.permissions中声明所需权限宿主/沙箱再用 SDK 提供的buildAllowAttribute工具函数转换成 allow 字符串src/app-bridge.ts应用声明的权限生成的 allow 指令cameracameramicrophonemicrophonegeolocationgeolocationclipboardWriteclipboard-write沙箱代理收到sandbox-resource-ready通知后先按声明设置allow属性再把 HTML 用document.write写入内层 iframeexamples/basic-host/src/sandbox.ts。测试用例可参考 src/app-bridge.test.ts。网络权限的另一半CSP 配置沙箱只管行为网络请求则由Content Security PolicyCSP管控。MCP Apps 的 HTML 没有同源服务器所以应用必须在资源元数据_meta.ui.csp中声明全部允许的域名docs/csp-cors.mdconnectDomainsfetch / XHR / WebSocket 可访问的域名含开发时的 localhostresourceDomains脚本、样式、图片、字体来源未声明时沙箱会套用严格默认值如object-src none、frame-src none官方示例中宿主把 CSP 通过 URL 查询参数传给沙箱页面再由服务器以HTTP 响应头下发响应头比meta标签更难被篡改见 examples/basic-host/src/implementation.ts。下面这个地图应用就依赖connectDomainsresourceDomains从跨源加载瓦片与脚本完整示例见 examples/map-server/ 与 examples/sheet-music-server/。一次完整的沙箱握手流程把上面各环节串起来宿主打开一个 MCP App 的完整时序为宿主在不同源URL 上加载沙箱代理 iframe带上 CSP 参数沙箱代理自检通过后向宿主发送ui/notifications/sandbox-proxy-ready宿主读取 View 的 HTML 资源通过ui/notifications/sandbox-resource-ready发送 HTML、CSP 与权限声明沙箱代理设置allow属性并把 HTML 写入内层 iframe此后沙箱代理只做消息中继宿主 ↔ 沙箱 ↔ View逐跳校验 originView 完成ui/initialize握手后宿主才下发工具调用参数。相关 SDK 方法sendSandboxResourceReady与onsandboxreadysrc/app-bridge.ts。关键文件速查 想了解什么看哪里协议规范与沙箱代理要求specification/2026-01-26/apps.mdx沙箱代理完整实现examples/basic-host/src/sandbox.ts宿主加载沙箱与消息桥接examples/basic-host/src/implementation.ts权限 allow 属性构建工具src/app-bridge.tsCSP 与 CORS 配置指南docs/csp-cors.md从零构建第一个 MCP Appdocs/quickstart.md沙箱安全测试tests/e2e/security.spec.ts一句话总结MCP Apps 宿主沙箱 跨源双层 iframe隔离sandbox 属性白名单能力收敛allow/CSP 双通道授权按需放行三者叠加让把服务器 HTML 直接渲染进聊天窗口这件事真正变得安全可控。【免费下载链接】ext-appsOfficial repo for spec SDK of MCP Apps protocol - standard for UIs embedded AI chatbots, served by MCP servers项目地址: https://gitcode.com/GitHub_Trending/ex/ext-apps创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
