服务注册与分布式协调 / 系统课时
发布多版本 MCP 服务
发布多版本 MCP 服务
同一个 MCP Server 升级工具参数或返回契约时,不应直接覆盖旧定义。本篇用版本化发布保留旧契约,再分别读取指定版本与默认版本,让客户端可以固定版本,也能在验证后安全切换默认版本。
学习目标
- 为同一 MCP Server 增加新版本而保留旧版本
- 识别工具契约中的兼容变更与破坏性变更
- 使用管理 API 按显式版本读取服务并验证版本共存
把版本看成契约快照
Nacos 的 MCP 服务详情包含当前版本信息和全部版本列表;查询详情时传入 version 可读取指定版本,不传则读取当前最新版本。版本记录包含版本号、发布时间和是否为最新版本等信息。([Nacos 官网][1])
这意味着版本号不只是部署标签,而是客户端可选择的工具契约快照。例如 1.0.0 的 get_order 只接收 orderId,1.1.0 增加可选参数 currency。旧客户端继续固定 1.0.0 时,不会因为新契约出现而被迫同步升级。

发布新版本而不切默认版本
假设 order-tools 已经存在 1.0.0,且它仍是默认版本。发布 1.1.0 时使用更新接口提交新的 versionDetail.version,同时把 latest 设为 false,先让新版本进入目录但不改变默认读取结果。MCP 管理 API 的更新接口为 PUT /nacos/v3/admin/ai/mcp,需要对应命名空间的写权限。([Nacos 官网][1])
下面示例假设原服务使用 streamable 协议,远端端点已经存在,因此不覆盖端点信息。若部署启用了鉴权,请按实际环境补充凭据。
NACOS="http://<HOST>:<PORT>"
MCP_ID="<ID>"
# 新版本先进入目录,不切换默认 latest
curl -sS -X PUT "${NACOS}/nacos/v3/admin/ai/mcp" \
-d 'namespaceId=public' \
--data-urlencode 'serverSpecification={"id":"<ID>","name":"order-tools","protocol":"streamable","frontProtocol":"streamable","description":"Order query tools","versionDetail":{"version":"1.1.0"},"enabled":true}' \
--data-urlencode 'toolSpecification={"tools":[{"name":"get_order","description":"Query an order","inputSchema":{"type":"object","properties":{"orderId":{"type":"string"},"currency":{"type":"string"}},"required":["orderId"]}}]}' \
-d 'latest=false'预期输出:
{"code":0,"message":"success","data":"ok"}其中 <HOST>、<PORT>、<ID> 要替换为实际值。接口成功只说明目录更新完成,不等于新版本已经通过业务验证。
记录工具契约变化
版本升级前先比较工具名、输入 Schema、返回语义和安全要求。一个实用原则是:新增可选字段通常可以做小版本升级,而删除字段、重命名工具、把可选字段改为必填,都会让旧调用方更容易失败,应按破坏性变更处理。
| 变化 | 示例 | 建议 |
|---|---|---|
| 新增可选参数 | currency 可省略 |
可作为兼容升级 |
| 新增工具 | 增加 list_orders |
通常兼容 |
| 删除或重命名工具 | get_order 改名 |
视为破坏性变更 |
| 可选改必填 | currency 必填 |
视为破坏性变更 |
版本号只能告诉使用者“发生了哪一轮变化”,不能替代契约审查。发布记录里应保留变更原因、兼容结论和回滚目标版本。
按版本读取并验证共存
发布后显式读取两个版本,最容易确认旧版本没有被覆盖。下面命令依赖 curl 与 Python 3,分别请求 1.0.0 与 1.1.0,只打印服务器实际返回的版本号。
NACOS="http://<HOST>:<PORT>"
MCP_ID="<ID>"
# 显式读取两个固定版本,避免默认指针影响验证
for VERSION in 1.0.0 1.1.0; do
curl -sS --get "${NACOS}/nacos/v3/admin/ai/mcp" \
--data-urlencode 'namespaceId=public' \
--data-urlencode "mcpId=${MCP_ID}" \
--data-urlencode "version=${VERSION}" \
| python3 -c 'import json,sys; print(json.load(sys.stdin)["data"]["versionDetail"]["version"])'
done预期输出:
1.0.0
1.1.0若显式读取旧版本失败,应先检查旧版本是否仍在 allVersions 中,再检查是否误用了相同版本号覆盖契约。只有在新版本验证通过后,才应考虑修改默认版本指针;在此之前,让生产调用方固定旧版本更安全。