MCP Apps UI元数据设计详解prefersBorder、domain与permissions完整指南【免费下载链接】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 是 MCPModel Context Protocol生态中让 AI 聊天机器人嵌入交互式 UI 的标准协议。本指南面向新手带你快速读懂官方规范中UIResourceMeta的三大核心字段——prefersBorder视觉边界、domain沙箱域名、permissions沙箱权限掌握 UI 资源的安全与渲染配置方法。一、UIResourceMeta 是什么一张 UI 的“说明书”当 MCP 服务器把一个 HTML 界面UI 资源提供给宿主如 Claude、IDE 插件渲染时不能只丢一份 HTML 过去——宿主还需要知道这个界面允许连接哪些外部网络CSP 策略需要哪些浏览器能力摄像头、麦克风等是否使用专属沙箱域名视觉上要不要加边框背景。这些配置统一放在_meta.ui字段中类型定义见 src/spec.types.ts完整规范见 specification/draft/apps.mdx。二、prefersBorder 一键配置界面要不要“框起来”prefersBorder是一个布尔值用来告诉宿主是否给 UI 加上可见的边框和背景取值效果true显示边框 背景界面像一个独立卡片false无边框无背景界面与宿主融为一体省略由宿主自行决定不同宿主默认值可能不同新手建议规范明确推荐显式指定该值因为各宿主的默认行为不一致显式声明可保证跨平台视觉一致性。如果你是从 OpenAI Apps 迁移过来旧字段_meta[openai/widgetPrefersBorder]就对应现在的_meta.ui.prefersBorder映射表见 docs/migrate_from_openai_apps.md。三、domain 专属源给沙箱一个稳定“门牌号”domain字段为 UI 的沙箱 iframe 指定一个专用源origin省略时宿主会使用默认沙箱源通常是按会话生成。它主要解决三类问题OAuth 回调第三方登录需要固定的回调域名CORS 策略API 服务端需要在响应头中放行特定源API Key 白名单某些服务按域名加白请求来源。⚠️注意域名格式由各宿主自行定义常见模式包括基于哈希的子域如{hash}.claudemcpcontent.com基于 URL 派生的子域如www-example-com.oaiusercontent.com。服务器开发者必须查阅目标宿主的文档确认格式不能假设统一规则。四、permissions 声明式权限只申请你需要的浏览器能力permissions字段声明 UI 需要哪些沙箱权限宿主可以据此设置内层 iframe 的allow属性。规范内置支持 4 种能力字段对应浏览器 Permission Policy用途cameracamera摄像头访问microphonemicrophone麦克风访问geolocationgeolocation地理位置clipboardWriteclipboard-write剪贴板写入两条关键规则要牢记“MAY”而非“MUST”宿主可以但不必须授予这些权限申请不等于批准做好降级规范建议 App不应假设权限已授予应使用 JS 特性检测feature detection作为兜底权限被拒时优雅降级。例如宿主侧的典型处理逻辑若声明了permissions.camera就把camera加入 iframe 的allow列表参考 specification/draft/apps.mdx 中的安全实现示例。五、元数据写在哪里resources/list 与 resources/read 二选一还是都写UIResourceMeta含 csp、permissions、domain、prefersBorder可以放在两个位置resources/list挂在资源条目的_meta.ui上适合作为静态默认值宿主在连接阶段即可审查安全配置无需拉取资源内容resources/read挂在每个内容项的_meta.ui上适合按响应动态覆盖。当两处同时存在时内容项resources/read的值优先。规范建议元数据动态变化时优先写在内容项上静态配置则写在列表级。SDK 侧通过registerAppResource的_meta.ui配置即可设置列表级元数据见 src/server/index.ts。六、安全底线宿主如何强制执行这些元数据CSP 强制宿主必须根据ui.csp中声明的connectDomains、resourceDomains、frameDomains、baseUriDomains构造 CSP 头未声明的域名一律拦截限制性默认若完全省略 CSP宿主持有最严格的默认策略如connect-src none保证“默认安全”只收紧不放宽宿主可以进一步限制但绝不能允许未声明的域名审计留痕宿主应记录 CSP 配置以便安全审查。 一句话总结prefersBorder 管“长相”domain 管“身份”permissions 管“能力”CSP 管“边界”——四者共同构成了 MCP Apps UI 的安全与渲染契约。延伸阅读完整协议规范specification/draft/apps.mdx、specification/2026-01-26/apps.mdx类型定义src/spec.types.ts服务端 SDKsrc/server/index.tsCSP 与 CORS 实践docs/csp-cors.md授权机制docs/authorization.md【免费下载链接】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 UI元数据设计详解：prefersBorder、domain与permissions完整指南
MCP Apps UI元数据设计详解prefersBorder、domain与permissions完整指南【免费下载链接】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 是 MCPModel Context Protocol生态中让 AI 聊天机器人嵌入交互式 UI 的标准协议。本指南面向新手带你快速读懂官方规范中UIResourceMeta的三大核心字段——prefersBorder视觉边界、domain沙箱域名、permissions沙箱权限掌握 UI 资源的安全与渲染配置方法。一、UIResourceMeta 是什么一张 UI 的“说明书”当 MCP 服务器把一个 HTML 界面UI 资源提供给宿主如 Claude、IDE 插件渲染时不能只丢一份 HTML 过去——宿主还需要知道这个界面允许连接哪些外部网络CSP 策略需要哪些浏览器能力摄像头、麦克风等是否使用专属沙箱域名视觉上要不要加边框背景。这些配置统一放在_meta.ui字段中类型定义见 src/spec.types.ts完整规范见 specification/draft/apps.mdx。二、prefersBorder 一键配置界面要不要“框起来”prefersBorder是一个布尔值用来告诉宿主是否给 UI 加上可见的边框和背景取值效果true显示边框 背景界面像一个独立卡片false无边框无背景界面与宿主融为一体省略由宿主自行决定不同宿主默认值可能不同新手建议规范明确推荐显式指定该值因为各宿主的默认行为不一致显式声明可保证跨平台视觉一致性。如果你是从 OpenAI Apps 迁移过来旧字段_meta[openai/widgetPrefersBorder]就对应现在的_meta.ui.prefersBorder映射表见 docs/migrate_from_openai_apps.md。三、domain 专属源给沙箱一个稳定“门牌号”domain字段为 UI 的沙箱 iframe 指定一个专用源origin省略时宿主会使用默认沙箱源通常是按会话生成。它主要解决三类问题OAuth 回调第三方登录需要固定的回调域名CORS 策略API 服务端需要在响应头中放行特定源API Key 白名单某些服务按域名加白请求来源。⚠️注意域名格式由各宿主自行定义常见模式包括基于哈希的子域如{hash}.claudemcpcontent.com基于 URL 派生的子域如www-example-com.oaiusercontent.com。服务器开发者必须查阅目标宿主的文档确认格式不能假设统一规则。四、permissions 声明式权限只申请你需要的浏览器能力permissions字段声明 UI 需要哪些沙箱权限宿主可以据此设置内层 iframe 的allow属性。规范内置支持 4 种能力字段对应浏览器 Permission Policy用途cameracamera摄像头访问microphonemicrophone麦克风访问geolocationgeolocation地理位置clipboardWriteclipboard-write剪贴板写入两条关键规则要牢记“MAY”而非“MUST”宿主可以但不必须授予这些权限申请不等于批准做好降级规范建议 App不应假设权限已授予应使用 JS 特性检测feature detection作为兜底权限被拒时优雅降级。例如宿主侧的典型处理逻辑若声明了permissions.camera就把camera加入 iframe 的allow列表参考 specification/draft/apps.mdx 中的安全实现示例。五、元数据写在哪里resources/list 与 resources/read 二选一还是都写UIResourceMeta含 csp、permissions、domain、prefersBorder可以放在两个位置resources/list挂在资源条目的_meta.ui上适合作为静态默认值宿主在连接阶段即可审查安全配置无需拉取资源内容resources/read挂在每个内容项的_meta.ui上适合按响应动态覆盖。当两处同时存在时内容项resources/read的值优先。规范建议元数据动态变化时优先写在内容项上静态配置则写在列表级。SDK 侧通过registerAppResource的_meta.ui配置即可设置列表级元数据见 src/server/index.ts。六、安全底线宿主如何强制执行这些元数据CSP 强制宿主必须根据ui.csp中声明的connectDomains、resourceDomains、frameDomains、baseUriDomains构造 CSP 头未声明的域名一律拦截限制性默认若完全省略 CSP宿主持有最严格的默认策略如connect-src none保证“默认安全”只收紧不放宽宿主可以进一步限制但绝不能允许未声明的域名审计留痕宿主应记录 CSP 配置以便安全审查。 一句话总结prefersBorder 管“长相”domain 管“身份”permissions 管“能力”CSP 管“边界”——四者共同构成了 MCP Apps UI 的安全与渲染契约。延伸阅读完整协议规范specification/draft/apps.mdx、specification/2026-01-26/apps.mdx类型定义src/spec.types.ts服务端 SDKsrc/server/index.tsCSP 与 CORS 实践docs/csp-cors.md授权机制docs/authorization.md【免费下载链接】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），仅供参考