在兼容旧客户端的同时将 HTTP MCP 服务器迁移至 2026-07-28

目标

本文反映截至 2026年10月25日的情况。将 HTTP MCP 服务器迁移至 2026-07-28 修订版，同时保留明确承诺支持的 2025-11-25 客户端路径。部署前，重新核对相应版本的传输规范、消息模式，以及所选 SDK 文档中声明的支持范围。这是一套建议的验收流程，并非已完成迁移测试的报告。

前提条件

盘点客户端协议修订版、初始化处理程序、会话存储、回调、订阅和授权策略。准备一个位于与生产环境同类网关之后的预发布端点、一份回滚配置，以及两个修订版各自的客户端。使用无害的测试工具和独立的测试身份。记录实际使用的 SDK 软件包版本；协议修订版并不等同于软件包版本。

步骤

1. 区分协议处理路径。兼容性规则允许同一个端点支持两种行为。旧版 initialize 选择旧版语义；新版的逐请求元数据选择无状态处理。只要仍支持旧版客户端，就应保留旧修订版协商确定的行为。不要将新版的请求头要求一概套用到旧版初始化流程上。

2. **让每个请求自包含。**要求 params._meta 包含 io.modelcontextprotocol/protocolVersion 和 io.modelcontextprotocol/clientCapabilities。按建议提供客户端身份，但绝不能将这种自行声明的身份用作授权依据。不要再从之前的连接推导能力或应用上下文。对于跨调用的状态，提供明确的标识符。

3. **实现发现功能与传输校验。**实现 server/discover，将版本同步写入 MCP-Protocol-Version，并对照请求体校验必需的请求头。对于无需身份验证的预发布端点，可使用以下发现功能冒烟检查：

   curl --request POST 'https://mcp.example.com/mcp' \
     --header 'Content-Type: application/json' \
     --header 'Accept: application/json, text/event-stream' \
     --header 'MCP-Protocol-Version: 2026-07-28' \
     --header 'Mcp-Method: server/discover' \
     --data '{"jsonrpc":"2.0","id":1,"method":"server/discover","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{},"io.modelcontextprotocol/clientInfo":{"name":"migration-check","version":"local"}}}}'
   

   将示例 URL 替换为实际地址。对于受保护的端点，使用该部署批准的、经过身份验证的测试客户端；不要为了执行检查而关闭身份验证。

4. **更新结果和交互流程。**为普通结果输出 resultType: "complete"。为允许交互的操作实现 MRTR：返回 input_required，然后在使用新请求 ID 的请求中，接收匹配的 inputResponses 和原样传回的不透明 requestState。当状态影响权限或业务逻辑时，应验证其完整性；按建议将其绑定到主体、过期时间和发起交互的操作。需要一次性使用时，在服务器端强制执行。

5. **迁移通知与缓存。**用 subscriptions/listen 替换独立的 GET 通知流。保留已使用的请求级 SSE，但移除 Last-Event-ID 恢复机制：关闭响应流即表示取消。对于缓存规范涵盖的完整结果，添加非负的 ttlMs 和适当的 cacheScope。中间结果和 MRTR 重试结果不得缓存。

6. **有针对性地测试版本恢复。**对于不受支持的新版协议版本，应返回 UnsupportedProtocolVersionError，并附上支持的版本。客户端应使用兼容版本重试。遇到 HTTP 400 时，检查 JSON-RPC 响应体：如果是可识别的新版错误，需要修正请求或选择版本；如果响应体为空或无法识别，则允许回退到旧版初始化。不要仅因一个有效的新版请求被拒绝就降级。

7. **测试部署边界。**在预发布环境中，通过网关执行发现、列表获取、一次无害调用、一次交互式重试和一次订阅。使用旧版客户端重复测试，并将新版请求分发到不同实例。中断一个无害的 SSE 响应，验证取消操作以及不依赖续传的安全恢复。验证每个身份的授权，并确认请求元数据原样到达服务器。

预期结果

两个受支持的修订版均能完成各自的工作流程。新版操作不需要传输会话；旧版客户端保留协商后的生命周期。在验收检查通过之前，保留旧配置以备使用。

限制与验证基础

引用的规范定义了协议行为；以上步骤是运维人员提出的验证计划。它们不能证明 SDK 兼容性、业务操作重试的安全性，或在某一具体负载均衡器上的运行效果。这些都需要针对具体部署进行测试。