Skip to main content
本文档列出自上一个修订版 2025-11-25 以来对模型上下文协议(Model Context Protocol,MCP)规范所做的变更。

重大变更

  1. 从 Streamable HTTP 传输中移除协议级别的会话和 Mcp-Session-Id header。列表端点(tools/listresources/listprompts/list)不再按连接变化。需要跨调用状态的服务器使用显式的、服务器铸造的句柄,作为普通的工具参数传递(SEP-2567)。
  2. 使 MCP 无状态:移除 initialize/notifications/initialized 握手。每个请求现在在 _meta 中携带其协议版本和客户端能力(io.modelcontextprotocol/protocolVersionio.modelcontextprotocol/clientCapabilities)。客户端应当(SHOULD)在每个请求上标识自己(io.modelcontextprotocol/clientInfo),服务器应当(SHOULD)在每个结果的 _meta 中标识自己(io.modelcontextprotocol/serverInfo)。版本不匹配返回 UnsupportedProtocolVersionErrorSEP-2575)。
  3. 添加 server/discover:服务器必须(MUST)实现此 RPC 以公布其所支持的协议版本、能力和身份。客户端可以(MAY)在任何其他请求之前调用它以进行预先的版本选择,或在 STDIO 上将其用作向后兼容性探测(SEP-2575)。
  4. subscriptions/listen 替换 HTTP GET 端点和 resources/subscribe/resources/unsubscribe:一个单一的、长期存在的 POST-响应流,用于选择加入的服务器到客户端的变更通知。客户端选择加入特定类型(toolsListChangedpromptsListChangedresourcesListChangedresourceSubscriptions);服务器确认并用 io.modelcontextprotocol/subscriptionId 标记通知。诸如 notifications/progressnotifications/message 之类的请求范围通知继续在它们所关联的请求的响应流上流动,而不是在 subscriptions/listen 流上(SEP-2575)。
  5. 移除 pinglogging/setLevelnotifications/roots/list_changed。日志级别现在通过 _meta 中的 io.modelcontextprotocol/logLevel 按请求设置;服务器不得(MUST NOT)为未包含此字段的请求发出 notifications/messageSEP-2575)。
  6. 将实验性的 tasks 移出核心协议,放入一个官方扩展(io.modelcontextprotocol/tasks)。重新设计的扩展用通过 tasks/get 进行的轮询替换了阻塞式的 tasks/result 方法,并新增一个用于客户端到服务器输入的 tasks/update,移除了 tasks/list,并允许服务器在无需按请求选择加入的情况下主动返回任务句柄(SEP-2663)。
  7. 引入多轮往返请求(Multi Round-Trip Requests,MRTR)模式,它替换了之前发送服务器发起请求(如 roots/listsampling/createMessageelicitation/create)的方法。服务器返回一个 InputRequiredResultresultType: "input_required"),其 inputRequests 字段携带处理该请求所需额外信息的请求。客户端在原始请求的重试中以 inputResponses 响应,提供所请求的信息。(SEP-2322)。
  8. 所有结果现在都携带一个必需的 resultType 字段:"complete" 用于普通结果,"input_required" 用于多轮往返请求的中间结果。客户端**必须(MUST)**将来自省略该字段的早期协议服务器的结果视为 "complete"SEP-2322)。
  9. 从 Streamable HTTP 传输中移除 SSE 流的可恢复性和消息重投递(Last-Event-ID header 和 SSE 事件 ID)。断开的响应流会丢失执行中的请求;客户端**必须(MUST)**以一个新的请求 ID 将其作为新请求重新发出(SEP-2575)。

次要变更

  1. ClientCapabilitiesServerCapabilities 添加 extensions 字段,以支持核心协议之外的可选扩展
  2. 记录 _meta 键(traceparenttracestatebaggage)的 OpenTelemetry 追踪上下文传播惯例(SEP-414)。
  3. 服务器**应当(SHOULD)**以确定性顺序从 tools/list 返回工具,以支持客户端侧缓存并提高 LLM 提示缓存命中率。
  4. 在 Streamable HTTP POST 请求上要求标准的 MCP 请求 header(Mcp-MethodMcp-Name),并通过 x-mcp-header 添加对来自工具参数的自定义 header 的支持(SEP-2243)。
  5. 通过一个新的 CacheableResult 接口,要求由 tools/listprompts/listresources/listresources/readresources/templates/list 返回的结果携带 ttlMscacheScope 字段。ttlMs 是一个新鲜度提示(以毫秒为单位),允许客户端缓存响应并减少轮询;cacheScope"public""private")控制共享的中间方是否可以缓存该响应。这两个字段补充现有的 listChanged 通知(SEP-2549)。
  6. 将资源未找到错误代码从 -32002 改为 -32602(Invalid Params),以与 JSON-RPC 规范对齐。
  7. 授权服务器**应当(SHOULD)RFC 9207 在授权响应中包含 iss 参数,而 MCP 客户端必须(MUST)**在兑换授权码之前对照记录的 issuer 校验存在的 issSEP-2468)。
  8. 要求 MCP 客户端在动态客户端注册期间指定一个适当的 application_type,以避免 OpenID Connect 重定向 URI 冲突(SEP-837)。
  9. 澄清客户端凭据被绑定到签发它们的授权服务器:客户端**必须(MUST)**以 issuer 标识符为键持久化凭据,**不得(MUST NOT)将它们与不同的授权服务器重用,并必须(MUST)**在授权服务器变更时重新注册(SEP-2352)。
  10. 放宽 inputSchemaoutputSchema 以允许任何 JSON Schema 2020-12 关键字,并允许 structuredContent 为任何 JSON 值。添加 $ref 解析要求和组合关键字(composition-keyword)资源界限(SEP-2106)。
  11. 移除 notifications/elicitation/complete 通知和 URL 模式征询请求的 elicitationId 字段,两者都是在 2025-11-25 中引入的。在多轮往返请求模式下,客户端通过重试原始请求来获知带外交互的结果,因此一个服务器发起的完成信号——以及用于关联它的标识符——不再契合协议。需要跨重试关联一次征询的服务器在 requestState 中编码它们自己的标识符。
  12. 定义一个错误代码分配策略,对 JSON-RPC 服务器错误范围进行分区:-32000-32019 仍为实现定义(现有的 SDK 用法予以沿用),-32020-32099 为 MCP 规范保留。相应地重新编号本草案中引入的错误代码——HeaderMismatch -32001-32020MissingRequiredClientCapability -32003-32021UnsupportedProtocolVersion -32004-32022——并将 HeaderMismatchError 添加到 schema 中,它此前仅存在于传输的散文描述中。

已弃用

此处列出的特性仍属于规范的一部分,但已根据特性生命周期与弃用策略计划移除。新的实现不应采用它们。已弃用特性登记表跟踪当前处于已弃用状态的每一个特性。
  1. 弃用 Roots、Sampling 和 Logging 特性(SEP-2577)。这些特性在弃用窗口期内仍完全可用,但新的实现不应为它们添加支持。建议的迁移:改为通过工具参数、资源 URI 或服务器配置传递目录或文件,而非 Roots;直接与 LLM 提供方的 API 集成,而非 Sampling;记录到 stderr(stdio)或使用 OpenTelemetry,而非 Logging。
  2. 将 HTTP+SSE 传输(自协议版本 2025-03-26 起弃用)根据特性生命周期策略重新分类为已弃用(SEP-2596)。迁移到 Streamable HTTP
  3. includeContext"thisServer""allServers"(自协议版本 2025-11-25 起软弃用)重新分类为已弃用(SEP-2596)。省略该字段或使用 "none";这些值将不迟于 Sampling 特性本身被移除。
  4. 弃用 OAuth 2.0 动态客户端注册协议(RFC7591)作为客户端注册机制,转而使用客户端 ID 元数据文档PR #2858)。它仍可用于与不支持客户端 ID 元数据文档的授权服务器的向后兼容。

其他 schema 变更

  1. schema.json 现在正确地反映了 minimum/maximum/default 的 TypeScript 定义是 number 而不仅仅是 integer。这是由于使用 --defaultNumberType integer 运行生成器所导致的(PR#2710)。

治理与流程更新

  1. 采用一个规范的特性生命周期与弃用策略,定义 Active、Deprecated 和 Removed 特性状态、一个最短十二个月的弃用窗口,以及一个已弃用特性登记表SEP-2596)。

流程变更

  1. 将基于 PR 的 SEP 工作流形式化,在 seps/ 目录中使用 markdown 文件、从 PR 派生的编号、发起人(sponsor)职责,以及通过 PR 标签进行的状态管理(SEP-1850)。

完整变更日志

有关自上一个协议修订版以来所做的所有变更的完整列表,参见 GitHub