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-apps

MCP Apps 是 MCP（Model 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	用途
`camera`	`camera`	摄像头访问
`microphone`	`microphone`	麦克风访问
`geolocation`	`geolocation`	地理位置
`clipboardWrite`	`clipboard-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 的安全与渲染契约。