系统权限授权接入(服务端)
本文面向负责 MCP Server、业务服务端和联调验收的开发者,说明如何为工具声明系统权限、理解平台的授权判定,并在 Tool Call 中安全读取用户已授权的数据。
系统权限接入采用“双层授权”模型:工具配置的应用插件 Scope 与宿主系统权限必须同时满足。只有应用插件授权记录成功,并且当前设备的系统权限可用时,平台才会调用强依赖该权限的工具。
接入目标
当 MCP 工具需要定位、麦克风、摄像头、蓝牙或日历等系统能力时,开发者只需在应用版本和工具配置中声明对应 Scope。平台负责在调用工具前完成授权判断、拉起索权交互,并把可透传的授权数据(当前只涉及地理位置权限)注入当前 Tool Call。
标准链路为:
- 在 Manifest 顶层的
permissions权限字典中声明 Scope 的scope_name、description和type; - 在
tools.<tool_name>.tool_permissions中引用所需 Scope,并通过is_must_need标记强弱关联、通过priority设置优先级,详见 Manifest 配置规范 鉴权与索权章节; - 用户触发工具后,平台同时检查应用插件维度授权状态和宿主系统权限状态;
- 任一强依赖权限未满足时,平台下发索权卡片,暂不调用工具;
- 全部强依赖权限满足后,平台调用 MCP 工具;如果存在可透传的授权数据,则写入
arguments._miniapp_permitted_data; - 业务服务端读取并校验当前 Tool Call 中的授权数据,完成业务处理。
系统权限授权与登录鉴权是两套独立能力。工具同时需要登录时,还应按 登录接入(服务端) 完成登录配置;仅需要系统权限时,不要为了索权额外开启登录。
名词解释
接入前准备
工具权限声明
权限需先在 Manifest 顶层的 permissions 权限字典中定义,再由 tools.<tool_name>.tool_permissions 关联到具体工具。以下示例声明精确定位 Scope,并将其配置为强关联权限:
以下 Scope 列表与 Manifest 配置规范的 scope_name 枚举保持一致;未列入该枚举的值(如 scope.addPhoneContact)不得写入配置。
位置权限互斥:
scope.userLocation、scope.userFuzzyLocation和scope.userLocationBackground在同一个工具中只能选择一个。需要不同精度或前后台语义时,应拆分工具或重新设计调用边界。
运行时授权判断
对于 is_must_need: true 的 Scope,平台会同时检查两层状态。应用插件维度授权成功只表示用户同意当前应用使用该能力,不代表设备上的系统权限仍然可用。
位置权限特殊说明:对于一方(豆包同主体)应用插件,以及三方应用插件中用户未登录 && 当前工具本身不依赖登录的场景,无需触发应用插件维度的位置权限索权。平台仍会根据宿主系统权限和当前是否取得可用位置完成后续处理,其他权限的授权规则不受影响。
服务端接收授权数据
授权检查通过后,如果平台拿到了当前 Scope 可透传的数据,会在调用 MCP 工具前把数据写入 arguments._miniapp_permitted_data。该字段以 Scope 名为 key,业务参数仍保持原有结构。
_miniapp_permitted_data 是平台保留字段,具有以下行为:
- 只有当前调用存在可透传数据时才出现;业务服务端必须允许字段缺失;
- 数据按 Scope 分组,一个工具声明多个 Scope 时不要假设每个 Scope 都会产生数据对象(当前仅精确位置权限会产生明确数据透传对象);
- 平台只会把授权检查结果用于当前 Tool Call,历史消息中的同名字段不能代表当前权限仍有效;
- 客户端、模型和普通业务参数不得自行伪造该字段;服务端只读取平台实际发起的 MCP 请求;
- 工具同时需要登录时,登录身份和 Token 仍通过对应 Header 传递,不能从该字段推断用户身份。
位置数据处理规则
精确位置属于敏感信息。只为当前明确业务目的使用,仅用于当前本次工具调用的结果封装中,日志中不得记录完整经纬度、地址或整段 _miniapp_permitted_data;如确需保存,应执行最小化留存、访问控制和到期删除。
调试与验收
Web 模拟器调试
使用 dbx dev 启动调试环境,并按 本地调试与预览 打开 Web 模拟器。当前 Sandbox 链路会从本次 Session 的业务信息中读取系统权限和定位信息
- 确认当前 Manifest 顶层的
permissions权限字典已声明目标 Scope,且正在调试的工具已通过tool_permissions引用该 Scope; - 模拟器链路弹起对话链路索权卡片时点击允许,即上传应用插件维度授权数据;
- 模拟器链路弹起Web定位弹窗时点击允许(模拟系统权限弹窗),即上传当前获取的真实位置信息;
- 位置场景确认
latitude、longitude均存在且非 0;模拟器会以当前上报时间生成impr_time; - 重新触发对话,观察是否先出现索权卡片,以及授权后是否真正发起 Tool Call;
- 检查当前 Tool Call 的
arguments._miniapp_permitted_data,不要用历史消息中的旧参数判断本次结果。
如果当前 Session 取不到定位信息,或者经纬度缺失、解析失败或为 0,模拟器会把定位系统权限视为“未确定”,不向授权下游传递位置数据。对于强依赖位置的工具,这会再次触发索权卡片。
验收矩阵
Sandbox 日志判断口径
位置强依赖场景的成功链路应同时满足:
- 应用插件授权记录中
scope.userLocation为已授权; - 本次授权请求携带的
ACCESS_FINE_LOCATION系统权限为已授权; - 本次 Session 能读取到非 0 的经纬度;
- 最终有效权限映射中
scope.userLocation为已授权; - Tool Call 的
arguments._miniapp_permitted_data.scope.userLocation存在。
常见问题
应用插件授权已经成功,为什么仍然重复出现索权卡片
优先检查宿主系统权限和本次 Session 的定位数据。对于强依赖 Scope,两层状态必须同时成功;只写入 user_miniapp_permission 并不足以放行。位置缺失、经纬度为 0 或系统权限状态为未确定,都会让本次有效 Scope 回到待授权状态。
授权通过后为什么没有 _miniapp_permitted_data
先确认工具声明的 Scope 与返回数据的 key 完全一致,再检查当前调用是否确实产生了可透传数据。摄像头、麦克风等权限通过并不意味着平台会自动生成媒体数据;_miniapp_permitted_data 只承载平台在当前调用中实际取得并允许透传的数据。
撤销后为什么历史消息里还能看到旧经纬度
历史消息保存的是当时 Tool Call 的参数快照,不是当前 Session 的权限来源。撤销后,新 Session 不会关联旧 Session 保存的定位信息;判断当前状态只能查看本次授权请求和本次 Tool Call,不能从历史消息反推当前权限。
为什么位置权限不能同时声明精确、模糊和后台定位
三个位置 Scope 的精度、系统权限和用户授权语义不同,平台在一个工具中只接受其中一个。需要不同语义时应拆分工具,并让每个工具声明最小必要权限。
上线检查
- 每个工具在
tool_permissions中引用的 Scope 都已在 Manifest 顶层的permissions权限字典中声明; tools下的工具键名与 MCP Server 暴露的名称完全一致;- 强依赖与弱依赖配置符合真实业务,弱依赖缺数据时已有降级逻辑;
- 同一工具没有同时声明多个位置 Scope;
- 服务端只读取当前 Tool Call 中的平台保留字段,不信任客户端或历史消息中的同名数据;
- 位置经纬度、范围和新鲜度均有校验,缺失或非法时不会使用固定值兜底;
- 日志、监控和错误响应不包含完整经纬度、地址或整段授权数据;
- Sandbox 已覆盖授权、拒绝、系统权限关闭、无定位、零坐标和撤销重建 Session;
- 真机已覆盖首次索权、系统设置中关闭权限、重新开启权限和重复调用;
- 已确认强依赖权限未通过时不会调用 MCP 工具,通过后会正确透传授权数据。