AZ.FN

简体中文

English

简体中文

English

外观

MCP版本与兼容性

1525 字约 5 分钟

AIAgentMCP版本管理

2026-07-24

MCP 版本管理需要特别谨慎，因为模型依赖 Tool 的名称、描述和 Schema 做出工具选择——任何变更都可能影响模型行为。

一、基本定义

MCP 版本管理涉及多个层面：

  • 协议版本：MCP 规范本身的版本
  • SDK 版本：TypeScript/Python SDK 的版本
  • Server 版本：每个 Server 实现的版本
  • Client 版本：Client 实现的版本
  • 能力版本：Tool、Resource、Prompt 的接口版本

二、为什么 MCP 版本管理特别敏感

与传统 API 不同，MCP 的"消费者"是模型：

  • 模型通过 Tool 名称选择工具
  • 模型通过描述理解工具用途
  • 模型通过 Schema 构造参数

这意味着：

  • 重命名 Tool → 模型可能找不到工具
  • 修改描述 → 模型可能错误选择工具
  • 变更参数 → 模型可能构造错误参数
  • 改变语义 → 模型可能产生意外行为

三、兼容性类型

类型含义示例
向后兼容新版本 Client 可以连接旧版本 ServerClient 2.0 连接 Server 1.0
向前兼容旧版本 Client 可以连接新版本 ServerClient 1.0 连接 Server 2.0
不兼容需要同时升级两端协议结构变更

四、Schema 演进策略

安全变更（向后兼容）

变更类型安全性说明
新增可选参数✅ 安全旧 Client 忽略新参数
新增 Tool✅ 安全不影响已有 Tool
新增 Resource✅ 安全不影响已有 Resource
扩展错误信息✅ 安全不影响正常路径
新增通知类型✅ 安全旧 Client 忽略未知通知

危险变更（不兼容）

变更类型风险说明
删除参数❌ 不兼容旧 Client 仍会发送该参数
修改参数类型❌ 不兼容旧 Client 发送错误类型
重命名 Tool❌ 不兼容模型找不到工具
修改 Tool 语义❌ 危险模型行为改变
删除 Tool❌ 不兼容模型调用失败
修改返回格式❌ 不兼容Client 解析失败

五、废弃策略

推荐废弃流程：

1. 标记为 deprecated（在当前版本）
   → 在描述中添加 "Deprecated: 请使用 new_tool"
   → 日志记录废弃警告

2. 提供迁移期（至少 2 个次要版本）
   → 旧 Tool 继续工作
   → 文档说明迁移路径

3. 正式发布移除通知
   → 在 Release Notes 中明确说明

4. 移除（在下一个主要版本）
   → 完全删除旧 Tool

六、工具重命名

如果必须重命名 Tool：

  1. 创建新名称的 Tool
  2. 保留旧名称作为别名（指向相同实现）
  3. 在旧 Tool 描述中标注废弃
  4. 提供至少一个版本的迁移期
  5. 最终移除旧名称

七、参数变更

场景策略
新增可选参数直接添加，设合理默认值
新增必填参数先作为可选添加 → 下个版本改为必填
删除参数先标记废弃 → 忽略该参数 → 下个版本移除
修改参数类型接受两种类型 → 下版本只接受新类型

八、协议版本协商

初始化握手时，Client 和 Server 交换支持的协议版本：

Client → Server: { protocolVersion: "2025-03-26" }
Server → Client: { protocolVersion: "2025-03-26" }

如果版本不兼容，初始化失败，双方可以：

  • 降级到共同支持的版本
  • 或报告不兼容错误

九、能力协商

通过 capabilities 对象，双方声明支持的功能：

  • 支持的 Tool 特性（如 listChanged）
  • 支持的 Resource 特性（如 subscribe）
  • 支持的 Prompt 特性

十、兼容性测试

测试类型目的
旧 Client + 新 Server验证向后兼容
新 Client + 旧 Server验证向前兼容
Schema 变更测试验证参数变更不破坏现有调用
描述变更测试验证模型仍能正确选择工具
废弃功能测试验证废弃标记正确显示

十一、发布说明

每个版本应包含：

  • 新增能力
  • 变更的能力（标注兼容性）
  • 废弃的能力（标注替代方案）
  • 移除的能力
  • 协议版本变化
  • 迁移指南

十二、常见误区

误区正确做法
随意重命名 Tool使用废弃 + 别名策略
直接删除参数先标记废弃，提供迁移期
修改 Tool 语义但保持名称创建新 Tool，废弃旧 Tool
忽视描述变更的影响测试模型选择准确性
不写迁移指南每次破坏性变更都提供迁移文档
认为小版本可以随意变更小版本也应遵循兼容性规则

十三、实践检查清单

十四、与其他概念的关系

十五、适用边界

适用于：

  • 维护长期运行的 MCP Server
  • 管理多个 Client/Server 版本共存
  • 规划 Tool 接口演进

不适用于：

  • 一次性脚本或原型
  • 内部使用且不暴露接口的 Server

十六、参考资料

  • MCP 官方规范 - https://modelcontextprotocol.io/specification
  • Semantic Versioning - https://semver.org/
贡献者: fly