重大变更
-
从 Streamable HTTP 传输中移除协议级别的会话和
Mcp-Session-Idheader。列表端点(tools/list、resources/list、prompts/list)不再按连接变化。需要跨调用状态的服务器使用显式的、服务器铸造的句柄,作为普通的工具参数传递(SEP-2567)。 -
使 MCP 无状态:移除
initialize/notifications/initialized握手。每个请求现在在_meta中携带其协议版本和客户端能力(io.modelcontextprotocol/protocolVersion、io.modelcontextprotocol/clientCapabilities)。客户端应当(SHOULD)在每个请求上标识自己(io.modelcontextprotocol/clientInfo),服务器应当(SHOULD)在每个结果的_meta中标识自己(io.modelcontextprotocol/serverInfo)。版本不匹配返回UnsupportedProtocolVersionError(SEP-2575)。 -
添加
server/discover:服务器必须(MUST)实现此 RPC 以公布其所支持的协议版本、能力和身份。客户端可以(MAY)在任何其他请求之前调用它以进行预先的版本选择,或在 STDIO 上将其用作向后兼容性探测(SEP-2575)。 -
用
subscriptions/listen替换 HTTP GET 端点和resources/subscribe/resources/unsubscribe:一个单一的、长期存在的 POST-响应流,用于选择加入的服务器到客户端的变更通知。客户端选择加入特定类型(toolsListChanged、promptsListChanged、resourcesListChanged、resourceSubscriptions);服务器确认并用io.modelcontextprotocol/subscriptionId标记通知。诸如notifications/progress和notifications/message之类的请求范围通知继续在它们所关联的请求的响应流上流动,而不是在subscriptions/listen流上(SEP-2575)。 -
移除
ping、logging/setLevel和notifications/roots/list_changed。日志级别现在通过_meta中的io.modelcontextprotocol/logLevel按请求设置;服务器不得(MUST NOT)为未包含此字段的请求发出notifications/message(SEP-2575)。 -
将实验性的 tasks 移出核心协议,放入一个官方扩展(
io.modelcontextprotocol/tasks)。重新设计的扩展用通过tasks/get进行的轮询替换了阻塞式的tasks/result方法,并新增一个用于客户端到服务器输入的tasks/update,移除了tasks/list,并允许服务器在无需按请求选择加入的情况下主动返回任务句柄(SEP-2663)。 -
引入多轮往返请求(Multi Round-Trip Requests,MRTR)模式,它替换了之前发送服务器发起请求(如
roots/list、sampling/createMessage或elicitation/create)的方法。服务器返回一个InputRequiredResult(resultType: "input_required"),其inputRequests字段携带处理该请求所需额外信息的请求。客户端在原始请求的重试中以inputResponses响应,提供所请求的信息。(SEP-2322)。 -
所有结果现在都携带一个必需的
resultType字段:"complete"用于普通结果,"input_required"用于多轮往返请求的中间结果。客户端**必须(MUST)**将来自省略该字段的早期协议服务器的结果视为"complete"(SEP-2322)。 -
从 Streamable HTTP 传输中移除 SSE 流的可恢复性和消息重投递(
Last-Event-IDheader 和 SSE 事件 ID)。断开的响应流会丢失执行中的请求;客户端**必须(MUST)**以一个新的请求 ID 将其作为新请求重新发出(SEP-2575)。
次要变更
- 向
ClientCapabilities和ServerCapabilities添加extensions字段,以支持核心协议之外的可选扩展。 - 记录
_meta键(traceparent、tracestate、baggage)的 OpenTelemetry 追踪上下文传播惯例(SEP-414)。 - 服务器**应当(SHOULD)**以确定性顺序从
tools/list返回工具,以支持客户端侧缓存并提高 LLM 提示缓存命中率。 - 在 Streamable HTTP POST 请求上要求标准的 MCP 请求 header(
Mcp-Method、Mcp-Name),并通过x-mcp-header添加对来自工具参数的自定义 header 的支持(SEP-2243)。 - 通过一个新的
CacheableResult接口,要求由tools/list、prompts/list、resources/list、resources/read和resources/templates/list返回的结果携带ttlMs和cacheScope字段。ttlMs是一个新鲜度提示(以毫秒为单位),允许客户端缓存响应并减少轮询;cacheScope("public"或"private")控制共享的中间方是否可以缓存该响应。这两个字段补充现有的listChanged通知(SEP-2549)。 - 将资源未找到错误代码从
-32002改为-32602(Invalid Params),以与 JSON-RPC 规范对齐。 - 授权服务器**应当(SHOULD)按 RFC 9207 在授权响应中包含
iss参数,而 MCP 客户端必须(MUST)**在兑换授权码之前对照记录的 issuer 校验存在的iss(SEP-2468)。 - 要求 MCP 客户端在动态客户端注册期间指定一个适当的
application_type,以避免 OpenID Connect 重定向 URI 冲突(SEP-837)。 - 澄清客户端凭据被绑定到签发它们的授权服务器:客户端**必须(MUST)**以 issuer 标识符为键持久化凭据,**不得(MUST NOT)将它们与不同的授权服务器重用,并必须(MUST)**在授权服务器变更时重新注册(SEP-2352)。
- 放宽
inputSchema和outputSchema以允许任何 JSON Schema 2020-12 关键字,并允许structuredContent为任何 JSON 值。添加$ref解析要求和组合关键字(composition-keyword)资源界限(SEP-2106)。 - 移除
notifications/elicitation/complete通知和 URL 模式征询请求的elicitationId字段,两者都是在2025-11-25中引入的。在多轮往返请求模式下,客户端通过重试原始请求来获知带外交互的结果,因此一个服务器发起的完成信号——以及用于关联它的标识符——不再契合协议。需要跨重试关联一次征询的服务器在requestState中编码它们自己的标识符。 - 定义一个错误代码分配策略,对 JSON-RPC 服务器错误范围进行分区:
-32000到-32019仍为实现定义(现有的 SDK 用法予以沿用),-32020到-32099为 MCP 规范保留。相应地重新编号本草案中引入的错误代码——HeaderMismatch-32001→-32020,MissingRequiredClientCapability-32003→-32021,UnsupportedProtocolVersion-32004→-32022——并将HeaderMismatchError添加到 schema 中,它此前仅存在于传输的散文描述中。
已弃用
此处列出的特性仍属于规范的一部分,但已根据特性生命周期与弃用策略计划移除。新的实现不应采用它们。已弃用特性登记表跟踪当前处于已弃用状态的每一个特性。-
弃用 Roots、Sampling 和 Logging 特性(SEP-2577)。这些特性在弃用窗口期内仍完全可用,但新的实现不应为它们添加支持。建议的迁移:改为通过工具参数、资源 URI 或服务器配置传递目录或文件,而非 Roots;直接与 LLM 提供方的 API 集成,而非 Sampling;记录到
stderr(stdio)或使用 OpenTelemetry,而非 Logging。 -
将 HTTP+SSE 传输(自协议版本
2025-03-26起弃用)根据特性生命周期策略重新分类为已弃用(SEP-2596)。迁移到 Streamable HTTP。 -
将
includeContext值"thisServer"和"allServers"(自协议版本2025-11-25起软弃用)重新分类为已弃用(SEP-2596)。省略该字段或使用"none";这些值将不迟于 Sampling 特性本身被移除。 - 弃用 OAuth 2.0 动态客户端注册协议(RFC7591)作为客户端注册机制,转而使用客户端 ID 元数据文档(PR #2858)。它仍可用于与不支持客户端 ID 元数据文档的授权服务器的向后兼容。
其他 schema 变更
schema.json现在正确地反映了 minimum/maximum/default 的 TypeScript 定义是number而不仅仅是integer。这是由于使用--defaultNumberType integer运行生成器所导致的(PR#2710)。
治理与流程更新
- 采用一个规范的特性生命周期与弃用策略,定义 Active、Deprecated 和 Removed 特性状态、一个最短十二个月的弃用窗口,以及一个已弃用特性登记表(SEP-2596)。
流程变更
- 将基于 PR 的 SEP 工作流形式化,在
seps/目录中使用 markdown 文件、从 PR 派生的编号、发起人(sponsor)职责,以及通过 PR 标签进行的状态管理(SEP-1850)。