升级:MCP 工具按聊天角色授权(ADR 0065)
本版本起,ai.mcpServers 接入的 MCP 工具和插件工具走同一套聊天角色授权(ADR 0065,角色见聊天角色)。
升级后会发生什么
这是行为变更。 已经绑给聊天 Agent(ai.agents.<name>.mcpServers)的 MCP 服务器,升级后立刻按新默认值收紧:
| 工具 | 升级前 | 升级后(不写 permit) |
|---|---|---|
上游标注 readOnlyHint: true 的工具 | 所有人可见 | 所有人可见 |
没有标注、标注为写(readOnlyHint: false),或同时标了 destructiveHint: true 的工具 | 所有人可见,执行前审批 | 只有全局主人(owner@global)可见 |
- 普通成员、
trusted、admin以及只在某个账号或会话里是owner的人,只能看到上游标注只读的工具。看不到的工具不在模型的工具列表里,discover/load_tool也找不到,deferredTools.alwaysLoadedTools写了也不会常驻。 - 每次调用前按角色存储里的当前角色再判一次:会话历史里重放的旧调用、回合中被撤销的角色、子 Agent 沿用的父回合工具都会被拒绝,trace 里记为
tool_denied,policy: mcp-permit。 - 上游标注只决定谁能用,不放宽审批:MCP 工具仍按「可能写」处理,执行前照常走审批、文件策略、网络白名单和危险工具硬闸。
- 多数官方 MCP 服务器(如 GitHub、文件系统)已经给读工具标了
readOnlyHint;没有标注的服务器,普通成员升级后会看不到它的任何工具。
下面这些入口的回合主体不是全局主人,同样只能用只读工具:
- 定时任务:到期时按创建者当前的角色重算,再降一档运行(
owner→trusted,trusted/admin→user)。所以全局主人创建的任务默认也用不了「仅主人」的 MCP 工具;任务的执行计划点名了这样的工具时,该工具会缺失,任务记为degraded。 - A2A(含跨进程 Mailbox 的远端信件,无论对端声明什么信任级别)与 zhin 自己的 MCP Server 入口(主体角色是
user/authenticated)。
查看收紧了哪些工具
zhin trace last(或zhin trace <回合 id>):被拒绝的调用记为tool_denied,策略mcp-permit。- 按服务器统计「所有人可用 / 仅主人」的计数会在后续版本出现在
zhin status与 Console 的 MCP 页(ADR 0065 P2)。在此之前,可以对照上游服务器的tools/list结果里各工具的annotations.readOnlyHint。
三种常见写法
permit 写在 ai.mcpServers 的每一项下,三个键都可以省略:
yaml
ai:
mcpServers:
- name: github
transport: stdio
command: npx
args: ['-y', '@modelcontextprotocol/server-github']
permit:
readOnly: everyone # 上游标注只读、且没被 tools 命中的工具;缺省 everyone
default: owner@global # 其余工具;缺省 owner@global
tools: {} # 按上游工具名覆盖;缺省 {}1. 全部给主人(默认值,不用写):普通成员只用只读工具,主人全量。不信任某个服务器的标注时,把只读工具也收回给主人:
yaml
permit:
readOnly: owner@global2. 按工具放宽或收紧:tools 的键是上游报告的原始工具名(不带服务器前缀,区分大小写),值是一个档位。
yaml
permit:
tools:
create_issue: trusted # 放宽:trusted 成员和定时任务也能用
merge_pull_request: [owner@global, private(*)] # 只在主人私聊里可用(数组各项都要满足)
delete_*: deny # 谁都不能用- 档位写法:
everyone(所有人)、deny(谁都不能用)、一个 permit 字符串(trusted、admin、owner@global、role(owner@global,admin@adapter)、platform:admin等,与插件工具的permissions一项相同),或这样的字符串数组(各项都要满足)。everyone/deny只能单独写,不能放进数组;空数组是配置错误。 - 匹配规则:精确名优先;没有精确名时,取字面字符最多的
*模式(create_*比*_issue多一个字面字符,所以优先);字面字符一样多的几个模式都要满足。名字里含非 ASCII 字符的工具只能被精确名命中。 *会匹配上游以后新增的工具:放宽时尽量写精确名,收紧(deny、owner@global)时再用通配。- 只放行列出的工具(白名单):同时写
default: deny和readOnly: deny,再在tools里列出要开放的工具。
某个 Agent 还可以在自己的绑定里再收窄一层(与服务器级取 AND,只能收窄,省略的键不额外限制):
yaml
ai:
agents:
helper:
mcpServers:
- name: github
permit:
default: deny
tools:
get_me: everyone3. 恢复旧行为(不推荐):
yaml
permit:
default: everyone风险:所有人都能看到并调用这个服务器的写工具。ai.agent.execApprovalMode 的默认值是 auto,审批交给自动审核,普通成员发起的写操作通过自动审核后就会执行。确实需要时,优先用写法 2 只放开具体工具。
配置写错会怎样
permit 下出现 readOnly / default / tools 以外的键、数组为空、everyone / deny 放进数组、permit 字符串写错(包括已移除的 master、scene_admin 等,报错会给出替代写法)、同一层重复的模式、同一个 Agent 里重复列出同一个服务器,启动时都会报错,不会把工具多放出去。