给 OpenCode 按 Agent 分配 MCP 工具
OpenCode MCP 连接与 Agent 工具权限分别配置;用 V2 mcp.servers、命名规则和独立资源权限,把文档工具只交给需要它的 Agent。

OpenCode 里的 MCP 服务可以保持连接,同时只向特定 Agent 开放工具。V2 用 mcp.servers 管连接,用 permissions 匹配工具动作;把工具交给真正需要的 Agent,比在所有任务里挂上整个工具目录更容易判断调用范围。
本文于 2026 年 11 月 21 日核对官方 MCP 文档、Agent 文档及 v2.3.2 标签。下例以公开文档检索为场景,不连接私人数据库,不演示 OAuth 或保存真实凭据;完整服务调用仍需读者在自己环境验收。MCP 的基本角色可先看协议入门。
服务 connected,为什么 Agent 还是看不到工具
连接成功只说明客户端与服务的连接路径可用。工具还要被发现、通过当前 Agent 的权限检查,并以客户端支持的方式提供给模型。服务能提供工具,也不代表模型会在这轮任务选择它。
V2 的远程服务写在 mcp.servers 下:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"servers": {
"docs": {
"type": "remote",
"url": "https://mcp.context7.com/mcp"
}
}
}
}
这是文档中公开服务地址的配置示例,可用性、认证与限制仍由服务方决定。运行 opencode mcp list 查看连接状态;需要认证时按服务说明处理,别为了绕过登录把陌生凭据写进项目。
V2 使用 disabled: true 保留配置但不连接,不是 enabled: false。在 /mcps 断开只改变当时连接状态,不会替你改配置。项目覆盖同名服务器时,会替换整个服务器对象;只补一个字段,可能把原来必需的其他字段一并覆盖掉。
怎样只给文档 Agent 开放这组工具
工具权限动作名是规范化后的 <server>_<tool>。服务器叫 docs,就能用 docs_* 匹配;原名称里的特殊字符会变成下划线,命名时应避免规范化后撞名。
把以下内容合并到同一份 V2 配置中:
{
"permissions": [
{ "action": "docs_*", "resource": "*", "effect": "deny" },
{ "action": "opencode_list_mcp_resources", "resource": "docs", "effect": "deny" },
{ "action": "opencode_read_mcp_resource", "resource": "docs:*", "effect": "deny" }
],
"agents": {
"docs-reader": {
"description": "Look up public library documentation and return supported answers",
"mode": "subagent",
"permissions": [
{ "action": "docs_*", "resource": "*", "effect": "allow" },
{ "action": "opencode_list_mcp_resources", "resource": "docs", "effect": "allow" },
{ "action": "opencode_read_mcp_resource", "resource": "docs:*", "effect": "allow" },
{ "action": "edit", "resource": "*", "effect": "deny" },
{ "action": "shell", "resource": "*", "effect": "deny" },
{ "action": "subagent", "resource": "*", "effect": "deny" }
]
}
}
}
全局先拒绝这一服务的工具,docs-reader 再用追加规则允许。这里还分开处理 MCP 资源列表和读取:它们是独立动作,不能只禁 docs_* 就认定资源也被禁了。示例允许的是“若该服务提供这些资源时可以读取”,不会凭空为服务增加资源。
这个 Agent 禁止编辑、Shell 与继续派生,但其他动作仍按有效配置处理。它不是完整的系统隔离,也不会让会写入的远程工具自动变成只读。权限顺序和子 Agent 的边界见权限配置文章。
Code Mode 会改变权限动作名吗
V2 默认启用 Code Mode,把 MCP 工具放进可执行的工具命名空间,不必全部直接列在提供方的原生工具列表中。配置某个服务器 codemode: false 可以改为直接暴露其工具;这不是 MCP 连接失败时的通用修复开关。
权限仍匹配规范化后的 <server>_<tool>。对 execute 设为 deny 会移除 Code Mode、直接列工具,嵌套工具仍执行自己的权限检查;不要用这个设置代替对具体工具的限制。
官方还说明,当某个 Agent 的权限拒绝了服务所有工具时,不会把该服务的初始化 instructions 加进它的系统提示。这有助于减少无关信息,但本文没有测量 Token 节省比例。若长会话仍超限,继续检查压缩与固定工具定义的关系。
工具在运行中新增,为什么下一步还找不到
先区分“最初就没权限”和“服务动态改变了工具目录”。#64117 报告 OpenCode 2.3.0、Windows、本地 stdio 服务发出 notifications/tools/list_changed 后,新工具没有及时出现在模型可调用列表。
正文和全部 4 条回复已读:机器人模拟把现象收窄到同一步内的目录刷新时序;其他参与者提供了候选修改与局部测试,也明确没有真实模型测试。截至查阅仍开放,不能把候选提交或 dev 上的结果当成 v2.3.2 已发布修复。
遇到类似情况,记录最初工具目录、通知时间、下一次请求实际可用工具,以及直接暴露还是 Code Mode。先在新消息或重新连接后复查是否出现,避免让模型反复编造不存在的调用。
怎样验证分配真的有效
用公开库文档提一个需要查证版本的问题,让主 Agent 交给 docs-reader。检查实际子 Agent 是否创建、是否调用了 docs_ 下对应工具、返回内容是否带可核对的出处。再确认主 Agent 自身没有直接调用被禁工具,也不能通过资源读取走另一条路。
如果已连接却不能使用,按顺序查规范化动作名、Agent ID、最后匹配规则、目录刷新和工具 Schema;模型连正常工具调用都做不了时,再回到OpenCode 接入说明。工具返回的文字也只是一份资料,不是用户的新指令,工具结果中的授权边界适用于这条路径。


