MCP 中文教程

主题

11.1 协议版本演进 ​

🎯 学习目标：一眼看清 MCP 每个版本改了什么、哪些写法已经过时、你的实现该对齐哪一版
⏱️ 预计时间：20分钟
📊 难度等级：⭐⭐

📌 一句话结论：MCP 的版本号是日期（YYYY-MM-DD），目前最新稳定版是 2026-07-28。这一版是破坏性重构——协议从"有状态 + 初始化握手"改成了"无状态 + 每请求自带元数据"。如果你在网上看到的中文资料还在讲 initialize 握手、Mcp-Session-Id 会话、WebSocket 传输，那些都属于 2025-11-25 及更早的旧模型。

📅 版本时间线 ​

🔍 逐版详解 ​

2024-11-05 —— 初版 ​

MCP 公开的第一个版本，奠定了协议的基本骨架。

核心内容：

  • JSON-RPC 2.0 消息模型
  • initialize / notifications/initialized 初始化握手（协商协议版本与能力）
  • HTTP + SSE 传输（两个端点：POST 发请求，GET 收事件流）
  • 三大服务器功能：工具（tools）、资源（resources）、提示词（prompts）
  • 客户端能力：roots、sampling
  • 工具方法：ping、logging/setLevel、resources/subscribe

⚠️ 目前绝大多数中文教程都停在这个版本。这条时间线上它已经是第 4 版之前的东西了。

2025-03-26 —— 授权与传输重写 ​

主要变更：

变更影响
新增基于 OAuth 2.1 的完整授权框架HTTP 传输的鉴权有了标准答案
Streamable HTTP 取代 HTTP+SSE从"两个端点"变成"单一 MCP 端点 + 每请求可选 SSE 流"
支持 JSON-RPC 批处理（batching）后续 2025-06-18 又被移除
新增工具注解（tool annotations）可标注工具是否只读、是否具破坏性

其他 schema 变更：ProgressNotification 增加 message 字段；新增 audio 内容类型；新增 completions 能力（参数自动补全）。

2025-06-18 —— 结构化输出与 Elicitation ​

主要变更：

变更影响
移除 JSON-RPC 批处理支持2025-03-26 刚加的，这版又去掉了
新增结构化工具输出structuredContent + outputSchema
MCP 服务器被归类为 OAuth Resource Server增加受保护资源元数据以发现授权服务器
客户端必须实现 Resource Indicators（RFC 8707）防止恶意服务器窃取访问令牌
新增 Elicitation服务器可在交互中请求用户补充信息
工具结果支持资源链接（resource links）工具能返回指向资源的引用
HTTP 后续请求必须带 MCP-Protocol-Version 头版本声明进入头部
生命周期操作从 SHOULD 提升为 MUST时序要求更严

其他：_meta 字段扩展到更多接口类型；CompletionRequest 增加 context；新增 title 字段（人类友好显示名，让 name 可以做程序标识符）。

2025-11-25 —— Tasks 与注册表 ​

主要变更：

变更影响
授权服务器发现支持 OpenID Connect Discovery 1.0更灵活的授权服务器发现
支持 icons 元数据工具/资源/提示词/实现都能带图标
通过 WWW-Authenticate 支持增量 scope 授权按需申请权限
工具命名规范指导命名更一致
URL 模式 Elicitation引导用户去外部 URL 完成交互
Sampling 支持工具调用（tools / toolChoice）sampling 能带上工具
OAuth Client ID Metadata Documents推荐的客户端注册机制
Tasks 实验性支持持久请求的轮询与延迟取结果

其他重要变更：

  • JSON Schema 2020-12 成为默认方言
  • 明确 stdio 传输可以用 stderr 记所有类型的日志（不只是错误）
  • Streamable HTTP 中无效 Origin 头必须返回 403 Forbidden
  • 输入校验错误应作为工具执行错误返回（而非协议错误），以便模型自我纠正
  • 允许服务器随时断开 SSE 流以支持轮询
  • Elicitation schema 支持默认值

2026-07-28 —— 无状态重构（当前最新）⭐ ​

这是自初版以来最大的一次改动。 官方在 changelog 里列了 9 条主要变更，其中前 2 条直接改变了协议的形态：

1. 移除协议级会话 ​

从 Streamable HTTP 传输中移除协议级会话和 Mcp-Session-Id 头。列表类端点（tools/list、resources/list、prompts/list）不再随连接变化。需要跨调用状态的服务器改用显式句柄（server-minted handles）作为普通工具参数传递。

2. 让 MCP 变成无状态 ​

移除 initialize / notifications/initialized 握手。每个请求现在自带协议版本与客户端能力，放在 _meta 里（io.modelcontextprotocol/protocolVersion、io.modelcontextprotocol/clientCapabilities）。版本不匹配返回 UnsupportedProtocolVersionError。

3. 新增 server/discover ​

服务器必须实现。用于声明支持的协议版本、能力和身份。客户端可以在任何其他请求之前调用它做前置版本选择，或在 stdio 上作为向后兼容探测。

4. subscriptions/listen 取代 GET 端点与资源订阅 ​

用 subscriptions/listen 取代 HTTP GET 端点和 resources/subscribe / resources/unsubscribe：单条长连接 POST 响应流承载客户端订阅的服务端变更通知。客户端按类型 opt-in（toolsListChanged、promptsListChanged、resourcesListChanged、resourceSubscriptions）。

5. 删除 ping、logging/setLevel、notifications/roots/list_changed ​

日志级别改为请求级 io.modelcontextprotocol/logLevel；服务器不得为没有携带该字段的请求发送 notifications/message。

6. Tasks 移出核心协议 ​

tasks 从实验特性变成官方扩展（io.modelcontextprotocol/tasks）。用 tasks/get 轮询取代阻塞式的 tasks/result，新增 tasks/update，移除 tasks/list。

7. 引入 MRTR（多轮请求） ​

取代"服务器主动发请求"（roots/list、sampling/createMessage、elicitation/create）。服务器返回 InputRequiredResult（resultType: "input_required"），客户端在重试时带 inputResponses。

规范原文：服务器不得发起 JSON-RPC 请求，客户端不得发送 JSON-RPC 响应。

8. 所有结果必须带 resultType ​

"complete" 或 "input_required"。客户端对省略该字段的旧服务器结果，必须按 "complete" 处理。

9. 移除 SSE 流可恢复性 ​

删掉 Last-Event-ID 头和 SSE event ID。响应流断了就在途请求即丢失，客户端必须用新 request ID 重新发起。

次要变更（同样影响实现） ​

变更说明
能力对象新增 extensions 字段支持核心协议之外的可选扩展
文档化 OpenTelemetry 链路上下文传播_meta 里的 traceparent / tracestate / baggage
工具列表应返回确定顺序便于客户端缓存、提升 LLM 提示缓存命中率
要求 Streamable HTTP POST 带 Mcp-Method、Mcp-Name 头并支持通过 x-mcp-header 从工具参数生成自定义头
列表与读取结果必须带 ttlMs + cacheScope新增 CacheableResult 接口
资源不存在的错误码 -32002 → -32602对齐 JSON-RPC 规范
授权响应应带 iss（RFC 9207），客户端必须校验防止授权码被挪用
动态客户端注册必须指定 application_type避免与 OpenID Connect 重定向 URI 冲突
客户端凭据绑定到签发它的授权服务器不得跨授权服务器复用
inputSchema / outputSchema 放开为任意 JSON Schema 2020-12 关键字structuredContent 允许任意 JSON 值
移除 notifications/elicitation/complete 与 elicitationId改由 MRTR 重试获知结果
定义错误码分配策略并重新编号-32020 / -32021 / -32022

废弃（Deprecated） ​

Roots、Sampling、Logging 三个特性被 SEP-2577 标记废弃。它们在废弃窗口内仍能工作，但新实现不应再支持。

官方给出的迁移方向：

废弃特性替代方案
Roots通过工具参数、资源 URI 或服务器配置传递目录/文件
Sampling直接对接 LLM 提供方 API
Loggingstdio 上写 stderr，或使用 OpenTelemetry

draft —— 下一版 ​

官方仓库里还有一个 draft 目录，是下一版规范的在写稿。不要把 draft 当作稳定版实现——它随时会变。生产实现请对齐最近的稳定版本号（当前为 2026-07-28）。

⚠️ 已删除 / 已废弃清单 ​

按"现在还能不能用"归类，方便你快速排查自己的实现：

彻底删除（不能再用了） ​

项目删除于替代方案
initialize / notifications/initialized2026-07-28每请求 _meta + server/discover
Mcp-Session-Id 头 / 协议级会话2026-07-28显式句柄作为工具参数
ping2026-07-28无（无状态协议不需要保活）
logging/setLevel2026-07-28请求级 _meta.io.modelcontextprotocol/logLevel
notifications/roots/list_changed2026-07-28目录改由工具参数/资源 URI 传递
resources/subscribe / resources/unsubscribe2026-07-28subscriptions/listen
HTTP GET 端点（SSE）2026-07-28subscriptions/listen
SSE 可恢复性（Last-Event-ID、event ID）2026-07-28用新请求 ID 重发
tasks/list2026-07-28tasks/get 轮询 + tasks/update
JSON-RPC 批处理2025-06-18逐个请求
HTTP+SSE 传输2025-03-26Streamable HTTP
notifications/elicitation/complete2026-07-28MRTR 重试

已废弃（还能用，但别新用） ​

项目状态建议
roots（客户端能力）废弃用工具参数或资源 URI
sampling（客户端能力）废弃直接对接 LLM API
logging（服务器能力）废弃stderr 或 OpenTelemetry

保留但有限制 ​

项目限制
-32002（资源不存在）旧服务器的码，客户端仍应接受；新实现不得发出
-32042（需要 URL 征询）仅 2025-11-25 使用，本版不得发出

🧭 我该对齐哪个版本？ ​

你的角色建议
新写一个 MCP 服务器对齐 2026-07-28，实现 server/discover，每个结果带 resultType
新写一个 MCP 客户端对齐 2026-07-28，做好对旧服务器的降级（见 11.2 迁移指南）
维护已有的旧版服务器优先补上 resultType 与 server/discover，这两个是兼容性关键
只想用现成 SDK关注 SDK 支持的协议版本，别自己去拼协议细节

📖 学习路径建议 ​

🔗 官方资料 ​

🧩 本页提到的变更，去哪深读 ​

本页只回答"改了什么"。想弄清"为什么改、怎么落地"，看这两节：

本页出现的概念深读章节
SEP-2575 / SEP-2243 / SEP-2549 等编号12.2 SEP 协议改进流程
Tasks 移出核心、能力新增 extensions 字段12.3 官方扩展体系
授权响应 iss 校验、application_type12.1 OAuth 2.1 授权体系
动手验证新版行为12.5 MCP Inspector 工具链

👉 下一小节：11.2 迁移到 2026-07-28

内容依据 MCP 官方规范整理 · 规范以 官方文档 为准

Copyright © 2024-2026 遇码 MeetCoding

遇码开源技术社区Gemini中文文档