MCP工具治理实战：从6个工具到几十个，我怎么管的
本文是《MCP实战手记》第二季生产落地篇的治理章：单工具能跑稳，不代表几十个工具交给agent就敢进生产——这正是"治理层"要解决的问题。本机内存与Redis多实例两种后端，均实测跑通。
0.开篇：agent失控的几种姿势
[本机跑通] 本文所有代码与Docker多实例实测均本机跑通。
做MCP工具治理，把几十个工具的调用权交给agent，事故就来了。前文（十）讲了高可用筹备、（十一）落地了MCP网关与无状态改造，单工具已能稳稳跑；但篇11我们只跑通一个店长群6个工具，真实零售是几十个门店×多类工具——工具一多，麻烦才刚开始：
- 撞名：
retail-cn和logistics各有一个get_report，agent按名字调，到底调到谁？ - 越权：
query_store需要store:read权限，guest身份的agent却拿到了调用结果。 - 不敢下线：v1有个bug，v2修好了，但谁也不敢把v1摘掉，怕有调用方还在用。
- 僵尸：某工具负责人离职，半年没人维护，却一直出现在发现列表里。
这四件事，靠"把工具往MCP一注册"解决不了，需要一个治理层：注册有复合键、发现有权限过滤、调用有权限拦截、版本能灰度能弃用、状态可观测。
什么时候需要治理（对号入座）：工具数<10先不急；≥10上ToolboxRegistry解决撞名与发现；团队≥2人或有权限风险加两层拦截；迭代频繁/要灰度加版本共存与灰度路由。
全文导览
篇12 是第二季生产落地篇的「治理章」：从 6 个工具讲到几十个、从单实例讲到多实例一致。全长 14 节，按阅读目的挑着看：
- 想先建立全貌：§1 治理层骨架 一张图讲清 Registry 管哪四件事
- 工具老撞名 / 想管权限：§2 复合键 · §3 两层权限拦截
- 要上灰度、不敢轻易下线：§4 版本共存+灰度 · §6 弃用状态机
- 关心接口兼容与平滑升级：§5 checksum 接口指纹
- 要一眼看清工具健康度：§7 可观测看板
- 生产多实例如何保持一致：§8 多实例一致性（Docker实测）
- 后续规划与求职转岗：§9 tenantId预埋 · §13 下篇预告 · §14 求职资产化
完整可运行代码在文末 §14 与开源仓库（
v12tag），国内访问：https://gitee.com/ethanliang2016/mcp-in-action
1.治理层骨架：一个ToolboxRegistry
核心接口只有八件事，两种实现可互换：
publicinterfaceToolboxRegistry{voidregister(ToolboxDefinitiondef);// 注册一个版本List<ToolboxDefinition>list(callerId,scopes,tenantId);// 发现层（带过滤）ToolboxDefinitionresolve(callerId,scopes,id,version);// 调用层（带拦截）voidsetGrayRoute(id,callerId,version);// 灰度voiddeprecate(id);// 标记弃用voidadvanceLifecycle();// 弃用状态机推进TreeMap<String,ToolboxDefinition>versions(id);// 列版本voidsetClock(Clockclock);// 注入时钟（便于测试）}默认实现InMemoryToolboxRegistry（演示用）；加--spring.profiles.active=redis切到RedisToolboxRegistry，多实例共享同一份状态。
Registry 不独立成服务——它挂在 MCP 协议的tools/list和tools/call两个方法上，作为治理钩子：
- 发现：
tools/list进来 →Registry.list(caller, scopes)按权限过滤出可见工具 → 返回Client； - 调用：Client选定工具发
tools/call→Registry.resolve(caller, scopes, id)先校验scope/版本/状态 → 通过才交给真正的MCP Server执行。
即list决定"agent看得到什么"，resolve决定"agent调得到什么"，治理就落在这两钩子上。
ToolboxDefinition：每个工具的长相
| 字段 | 含义 | 治理用途 |
|---|---|---|
id = ToolboxId(ownerTeamId, name) | 复合键 | 解决跨团队撞名 |
version | SemVer | 同id多版本共存 |
requiredScope | 调用所需scope | 调用层拦截 |
tags/owner/docUrl | 元数据 | 发现/审计 |
status | ACTIVE/DEPRECATED/REMOVED/TOMBSTONE | 生命周期（TOMBSTONE=永久迁移路由） |
checksum | 接口指纹 | 接口变才变 |
tenantId | 租户 | 多租户隔离（篇13） |
successRate/p99Millis/errorRate | 健康度 | 看板 |
把篇11的6个工具注册成Toolbox（示例）
篇11的店长群6个工具（查库存/查订单/查设备/补货/上下文/回卡片），每个都包成一个ToolboxDefinition：
registry.register(ToolboxDefinition.builder().id(ToolboxId.of("retail-cn","check_stock")).version("1.0.0").requiredScope("stock:read").owner("张三").tags(List.of("inventory","store")).build());其它5个同理，换name/requiredScope/owner即可——现有的工具就这样"包一层"变成治理对象。
规模数据（本机实测）：注册50个Toolbox、list过滤查询<1ms；内存后端撑500个工具无压力，Redis后端瓶颈在网络RTO而非注册表本身。
为什么值得治（价值量化）
（零售行业典型估算）不治理时，新人接手陌生工具平均花2天、每季度因误调出1次故障、每月因越权报警1次；上了治理层后，撞名/越权事故约降80%、误调故障约降60%、僵尸工具归零。治理不是免费的——Registry维护约0.5人日/周，但省下故障处理约2人日/周，净赚1.5人日。
治理三问（评论区高频）
- Q：1人团队也要治吗？ A：工具少于10个不必，等规模上来再上Registry，成本低。
- Q：自研还是现成？ A：本文Registry约200行，能自研就自研避免重依赖；要企业级再上专业网关。
- Q：要数据库吗？ A：单机内存后端够用；多实例/生产才需Redis（第8节实测）。
2.复合键：同名不同团队不打架
ToolboxId由ownerTeamId + name组成。这样retail-cn/get_report和logistics/get_report是两个独立工具，agent传完整id才能解析，从根上消除歧义。
3.两层权限拦截：发现层+调用层
只拦调用不够——发现列表里就不该出现无权限的工具。
// 发现层：admin(*)看到全部，guest无scope则被过滤List<ToolboxDefinition>adminView=registry.list("admin",List.of("*"),null);// 3个版本List<ToolboxDefinition>guestView=registry.list("guest",List.of(),null);// 0个// 调用层：真正调之前再校验一次registry.resolve("guest",List.of(),getReport,null);// 抛 SecurityExceptionregistry.resolve("admin",List.of("*"),getReport,null);// 放行实测（seed实例）：发现层：admin看到3个版本；guest看到0个；调用层：guest调get_report被拦 -> caller无scope:report:gen。
scope匹配规则：*匹配所有工具；report:*匹配report域下所有子scope（如report:gen）；精确匹配则要求caller的scopes里完全相等。
默认最小权限：工具若未配
requiredScope视为公开（可见可调）；生产建议反设为"无 scope 不可见"，公开工具显式打标，避免漏配变越权（见散点文03）。
scope 匹配统一小写归一（caller 传Report:Gen与工具配report:gen视为同权），避免大小写不一致误判 403（见散点文03）。
4.版本共存+灰度：新版本先给canary
同一id注册v1、v2，默认稳定版是最先注册的那版（setIfAbsent）。灰度让特定caller固定走新版本：
registry.setGrayRoute(getReport,"canary","2.0.0");ToolboxDefinitioncanary=registry.resolve("canary",List.of("report:gen"),getReport,null);// v2.0.0ToolboxDefinitionnormal=registry.resolve("normal",List.of("report:gen"),getReport,null);// v1.0.0实测：灰度：canary命中2.0.0；normal命中1.0.0。灰度配置写入Redis后，另一个实例也能读到——这点第8节验证。
回滚：registry.setGrayRoute(id, callerId, null)即清除该caller的灰度，回到稳定版，无需发版。
5.checksum：接口指纹，接口变才变
工具"能不能平滑升级"取决于接口是否变。用sha256(方法签名|参数schema|返回值schema)做指纹：
checksum = sha256(get_report(storeId) | {"storeId":"string"} | {"text":"string"})真实Java计算（Java 17MessageDigest）：
byte[]digest=MessageDigest.getInstance("SHA-256").digest(combined.getBytes(StandardCharsets.UTF_8));Stringchecksum=HexFormat.of().toHexDigits(digest);// 转16进制指纹实测两版本哈希不同：v1.0.0=45fa7e9bd128...v2.0.0=91468b7489e2...。实现里微调（只改日志文案、不动签名/schema）哈希不变——可据此判断"是否破坏兼容"。
对于schema哈希判断不了的"行为变更"（如改了SQL查询逻辑但接口签名没变），人工标记breaking:true，强制触发兼容性校验——哈希管"接口变没变"，人工标记管"行为变没变"。
6.弃用状态机：DEPRECATED→REMOVED(stub)
不删，先标期，给调用方迁移窗口：
registry.deprecate(queryStore);// -> DEPRECATEDregistry.setClock(Clock.fixed(now+15d,UTC));// 模拟宽限到期registry.advanceLifecycle();// 宽限>=14天 -> REMOVED(stub)registry.resolve("admin",List.of("*"),queryStore,null);// 抛 IllegalStateException + 迁移指引实测：deprecate(query_store) -> status=DEPRECATED；宽限15天后advanceLifecycle() -> status=REMOVED；resolve已移除 -> Toolbox已移除:retail-cn/query_store，迁移指引见...。REMOVED不再出现在发现列表，但保留stub一段时间，调用时返回docUrl指引迁移。
延伸（见散点文02）：stub 30 天期满不物理删除，转而进入TOMBSTONE态——永久保留迁移路由，调用仍返回 410+docUrl，不丢迁移路径；深度文为控篇幅只画三态，生产以 TOMBSTONE 长期保留为准。
推进不靠手点：advanceLifecycle()由 Spring@Scheduled每天凌晨扫一次所有 DEPRECATED 工具，宽限期满（≥14天）自动推进到 REMOVED；需要立即生效时手动调一次也行。
多实例部署注意：每个实例都会触发该
@Scheduled，需加分布式锁（如 ShedLock）保证仅主节点推进，避免重复推进状态 + 重复通知 owner——完整实现见散点文02。
7.可观测看板：GET /api/toolboxes
治理的尽头是"一眼看清"。暴露一个只读视图ToolboxView（脱敏，不暴露schema细节）：
[{"name":"get_report","version":"1.0.0","status":"ACTIVE","ownerTeamId":"retail-cn","successRate":99.2},{"name":"get_report","version":"1.0.0","status":"ACTIVE","ownerTeamId":"logistics","successRate":99.2},{"name":"check_stock","version":"2.1.0","status":"ACTIVE","ownerTeamId":"retail-cn","successRate":97.5},{"name":"query_order","version":"1.4.0","status":"ACTIVE","ownerTeamId":"logistics","successRate":88.3},{"name":"query_store","version":"3.0.0","status":"DEPRECATED","ownerTeamId":"retail-cn","successRate":95.1},{"name":"push_card","version":"1.0.0","status":"DEPRECATED","ownerTeamId":"retail-cn","successRate":92.0}]successRate/p99Millis/errorRate由监控回填，是发现"慢工具""坏工具"的第一信号。
8.多实例一致性：Redis后端[Docker实测]
内存实现单机够用，但生产是多副本。治理状态（注册/灰度/弃用）必须跨实例一致，否则A实例弃用了某个工具，B实例还在放行。
做法：RedisToolboxRegistry把每个版本存为Redis hash（tb:{ownerTeamId}:{name}field=version），灰度路由单独存tb:gray:{id}，稳定版存tb:default:{id}；注册/弃用时向channeltoolbox-events发pub/sub事件。读统一走Redis——天然多实例一致。
我用Docker起Redis，跑两个实例验证（A播种、B只读）：
# 实例A（种子） java -jar toolbox-mcp.jar --server.port=8088 --spring.profiles.active=redis --toolbox.demo.seed=true # 实例B（非种子，读A写入的共享状态） java -jar toolbox-mcp.jar --server.port=8089 --spring.profiles.active=redis --toolbox.demo.seed=false两个实例的GET /api/toolboxes输出逐字节一致：
A :8088 -> [get_report@1.0.0 logistics, get_report@1.0.0 retail-cn] B :8089 -> [get_report@1.0.0 logistics, get_report@1.0.0 retail-cn] # 完全一致更关键的是"B读到的是A改动后的状态"：A把query_store推进成REMOVED后，B的发现列表里它已消失；A给canary配的灰度v2.0.0，B的resolve("canary")也命中v2.0.0。B日志：非种子实例读到query_store状态=REMOVED（与种子实例一致，证明弃用状态跨实例同步）。pub/sub事件两个实例都收到（[redis-pubsub]收到失效事件:retail-cn/get_report…）。
多实例时序（简化）：
caller ──> 实例A ──register/deprecate──> Redis ──pub/sub──> 实例B │ ▲ │ caller ──> 实例B ──────────────────────────┘ list/resolve读同一份状态生产建议：读走Redis + 本地Caffeine缓存，pub/sub事件触发缓存失效；Redis不可用时走降级白名单（只读缓存、放行白名单内工具），避免治理状态不可用拖垮调用链。
Redis 生产需开哨兵/集群避免单点；本地缓存层完整实现（键含版本、健康探活缓存、回源自愈）见散点文04。
结论：治理状态下沉到Redis，实例无状态，水平扩容不影响一致性。
9.tenantId预埋：多租户隔离留给篇13
ToolboxDefinition已带tenantId字段，本期留空=全局。list()/resolve()里已写好过滤：
if(def.getTenantId()!=null&&tenantId!=null&&!def.getTenantId().equals(tenantId))returnfalse;// 租户隔离实测：tenantId预埋：当前工具tenantId=null（null=全局；篇13多租户填此字段即隔离，本篇代码不用改）。篇13专门讲多租户模型，本篇零改动即可接入。
10.互链矩阵：本篇在系列中的位置
- （七）安全接入：本篇
requiredScope拦截是其"工具级"落地 - （八）无状态改造 / （九）生产化 MCP Server 的 6 层安全防护：本篇
RedisToolboxRegistry让治理状态也无状态 - （十）高可用筹备、（十一）MCP网关与无状态改造：本篇治理层挂在网关之后，是"敢交给生产"的最后一块
- （十三）多租户：直接消费本篇
tenantId字段
11.本篇Q&A
- Q：灰度怎么回滚？A：把
tb:gray:{id}里该caller的字段删掉（或指回稳定版）即刻生效，无需发版。 - Q：checksum会碰撞吗？A：sha256碰撞概率可忽略；更稳妥可在指纹里加入"破坏性变更标记"人工置位。
- Q：Redis挂了实例还能跑吗？A：本篇实现读强依赖Redis；生产应加本地缓存+降级白名单，pub/sub事件触发失效（本篇已发事件，接缓存水到渠成）。
- Q：僵尸工具怎么清？A：
advanceLifecycle()到REMOVED后保留stub约30天，期满由清理任务转为 TOMBSTONE（永久保留迁移路由，见散点文02），不再物理删除丢失迁移路径。
12.验证清单（本篇均可复现）
- 复合键：
retail-cn/get_report与logistics/get_report独立共存 - 发现层过滤：admin见3/guest见0（seed实例，含ACTIVE的query_store）
- 调用层拦截：guest无scope被
SecurityException拦下 - 灰度：canary→v2.0.0，normal→v1.0.0
- checksum：v1/v2哈希不同
- 弃用状态机：DEPRECATED→(>=14d)→REMOVED→(>=30d)→TOMBSTONE，resolve返回迁移指引
- 看板：GET /api/toolboxes返回脱敏视图
- 多实例：A/B两实例GET输出一致，灰度与弃用状态跨实例同步（Docker+Redis实测）
- tenantId：字段就位、过滤逻辑就位、本期为空
本篇收获清单（截图保存）：
- ToolboxRegistry 8个接口（注册/发现/调用/灰度/弃用/状态机/版本/看板）
- 复合键
ownerTeamId+name，跨团队同名不打架 - 两层权限拦截（发现层过滤 + 调用层
SecurityException） - caller级灰度 + 一行回滚
null - checksum = 签名+schema哈希，人工
breaking:true兜底行为变更 - 弃用状态机：14天宽限 + 30天stub + TOMBSTONE永久保留迁移路由
- Redis多实例一致性（pub/sub + 共享状态，A/B逐字节一致）
13.下篇预告
（十三）多租户Toolbox：同一套治理层，按tenantId做数据隔离、配额与计费，复用本篇全部代码。
篇12 还拆出四篇延伸篇，逐个放大治理层细节，关注不迷路：①版本灰度实战（caller 路由到指定版本）②弃用迁移实战（deprecate→removed 全链路）③权限评分实战（scope 拦截 + 健康度指标）④多实例一致性深潜（Redis 与本地缓存降级）。
14.求职资产化：岗位对照、一键启动与CTA
能力→岗位对照（这套治理能力能投什么岗）：
ToolboxRegistry/注册发现 → DevOps平台 / 内部开发者门户（JD关键词：服务注册 / 配置中心 / 工具治理）- 版本共存 + 灰度路由 → 发布工程 / SRE发布（JD关键词：灰度发布 / 金丝雀 / 回滚）
- 两层权限拦截 / scope → IAM / 零信任接入（JD关键词：OAuth2 / 权限模型 / 最小权限）
- 健康度看板 / 弃用状态机 → SRE / 可观测性（JD关键词：SLI / 告警 / 生命周期治理）
本机一键启动：JDK17+，git clone仓库后mvn spring-boot:run，内存后端无需Redis，即可看到GET /api/toolboxes输出；要测多实例再加--spring.profiles.active=redis起两个端口。
生产部署目标栈：Linux x86_64 / JDK 21 / Redis 7（Linux 容器）。
redis:7镜像即 Linux 容器，本文 Docker 多实例实测就在此栈上完成；"本机"指作者开发机（命令跨平台一致，编译产物.jar与 Linux 生产完全一致），无 Windows 专属依赖。
本篇北极星指标：Gitee star 目标50+，发布后7天核对搜索流量（关键词"MCP工具治理"）。
资产化CTA：仓库已开源，打了v12tag，一键启动demo见README；觉得有用欢迎star，下一篇（十三）讲多租户。
声明：本篇无外部密钥；demo配置均为本机值，未含任何生产凭据。
