结论

• apim中rest实现的mcp，不需要更新2.0，它是不为2.0取决于客户端和后端服务
• apim中mcp实现的mcp-server，需要有版本控制，版本不对，会出现问题
• apim中的服务，如果中间走了聚合mcp服务，它返回的mcp版本取决于聚合服务的mcp版本

name: MCP Dual Era Support
overview: 在 carbon-apimgt 中让网关北向（客户端↔网关）与南向（网关↔MCP 后端）同时支持 MCP 1.0（2025-06-18，有会话）与 MCP 2.0（2026-07-28，无状态），并在客户端与后端协议世代不一致时由网关做转译。
todos:

• id: phase0-constants
  content: 扩展 APIConstants.MCP（2026-07-28、server/discover、Mcp-Method/Name）；Publisher 校验 protocolVersion；CORS 增加新头
  status: pending
• id: phase1-negotiate
  content: 实现北向协议探测（Negotiator），写入 MessageContext；支持 Mcp-Method 与 _meta
  status: pending
• id: phase1-handlers
  content: 改造 McpInitHandler/MCPUtils/MCPPayloadGenerator/McpMediator：dual-era initialize/discover、session 策略、GET /mcp 行为
  status: pending
• id: phase2-fetcher
  content: MCPInitializerAndToolFetcher 按 protocolVersion 走 1.0 session 或 2.0 无状态发现，并回写 metadata
  status: pending
• id: phase2-proxy-translate
  content: SERVER_PROXY：元数据注入后端版本 + MCPProtocolTranslator 四象限透传/转译 + legacy session 缓存
  status: pending
• id: phase3-crosscut
  content: Throttle/Analytics/APIKeyValidator/CORS 对齐双协议 method 与版本字段
  status: pending
• id: phase4-tests
  content: 补齐协商/转译/Fetcher/限流单测与南北向 6 类验收场景
  status: pending
  isProject: false

MCP 1.0 / 2.0 南北向双协议支持任务清单

背景与目标

当前实现锁定 MCP 1.0 Streamable HTTP（2025-06-18）：

• 北向：强制 initialize + params.protocolVersion 校验；回复版本写死；Mcp-Session-Id 仅 CORS expose，不签发/校验
• 南向：SERVER_PROXY 大多透传；MCPInitializerAndToolFetcher 写死 initialize→session→tools/list
• MCPServerDTO.protocolVersion 已落 AM_API_METADATA，但运行时未使用

目标：同一网关实例对 MCP 1.0 与 2.0 客户端、1.0 与 2.0 后端均可工作；南北协议可不同，由网关转译。

flowchart LR Client10[MCP1_Client] Client20[MCP2_Client] GW[Gateway_DualEra] BE10[Backend_MCP1] BE20[Backend_MCP2] Client10 --> GW Client20 --> GW GW -->|"legacy dialect"| BE10 GW -->|"modern dialect"| BE20

协议世代约定（本方案固定）：

• Legacy / MCP 1.0 = 2025-06-18（initialize + Mcp-Session-Id）
• Modern / MCP 2.0 = 2026-07-28（无握手/无会话；_meta；server/discover；Mcp-Method / Mcp-Name）

配置模型（固定）： 每个 MCP Server 的 metadata.protocolVersion 表示 南向后端 协议；北向按请求自动探测（header / method / _meta / initialize），写入 MessageContext，再与后端版本比较决定透传或转译。

Phase 0 — 协议常量与元数据

1. 扩展 APIConstants.MCP
   • 增加 PROTOCOL_VERSION_2026_JULY = "2026-07-28"
   • SUPPORTED_PROTOCOL_VERSIONS = [2025-06-18, 2026-07-28]
   • 增加方法：METHOD_SERVER_DISCOVER = "server/discover"
   • 增加头：HEADER_MCP_METHOD = "Mcp-Method"、HEADER_MCP_NAME = "Mcp-Name"
   • 增加 era 辅助常量 / 判定方法名（legacy vs modern）
2. Publisher 校验：创建/更新 MCP Server 时 protocolVersion 必须属于上述集合；默认仍 2025-06-18（兼容现网）
   • 触点：PublisherCommonUtils、APIMappingUtil、OpenAPI publisher-api.yaml
3. CORS：在现有 MCP-Protocol-Version / Mcp-Session-Id 基础上，强制 allow/expose Mcp-Method、Mcp-Name

Phase 1 — 北向 Dual-Era（客户端 → 网关）

核心文件：McpInitHandler、MCPUtils、MCPPayloadGenerator、McpMediator

1. 协议探测（新工具类，建议 MCPProtocolNegotiator）
   • Legacy 信号：method=initialize 或存在 Mcp-Session-Id
   • Modern 信号：MCP-Protocol-Version: 2026-07-28，或 body _meta.protocolVersion，或 Mcp-Method，或 server/discover
   • 结果写入 MessageContext：MCP_PROTOCOL_VERSION、MCP_PROTOCOL_ERA
2. 方法解析：优先 Mcp-Method 头，回退 JSON-RPC method；保证 throttle/auth/analytics 与 2.0 头驱动一致
3. ALLOWED_METHODS + processInternalRequest
   • 增加 server/discover（网关自建 MCP 时返回 capabilities / serverInfo，替代 2.0 握手）
   • Legacy：保持 initialize / notifications/initialized 流程
   • Modern：允许首包直接 tools/list / tools/call / server/discover（不要求先 initialize）
4. validateInitializeRequest / getInitializeResponse
   • 接受 1.0 与 2.0 版本字符串；回复 echo 协商版本（不再写死）
   • Modern 客户端若误发 initialize：返回明确错误或兼容降级（本方案：兼容应答并标记 era=legacy for this connection，避免硬拒）
5. 鉴权例外（isNoAuthMCPRequest）
   • Legacy：维持现有 ping / notification / resources / prompts
   • Modern：将 server/discover 纳入与 initialize 同级策略（本方案：需认证，与 tools/list 一致，避免未授权探测；若产品要求公开 discover，可再改配置开关）
6. Session
   • Legacy：initialize 成功时签发 Mcp-Session-Id 响应头；后续 POST/GET 可选携带（本方案：不强制校验粘滞，但透传/存储到 context 供南向 1.0 使用）
   • Modern：不签发、不要求 Mcp-Session-Id
7. Streamable GET /mcp
   • Legacy：保持现有 SSE preamble（自建）/ SERVER_PROXY 透传
   • Modern：自建路径返回 405 或空闲置通道说明（本方案：对 modern 请求返回 405 Method Not Allowed，因 2.0 无 server-initiated 回推依赖）；SERVER_PROXY 仍透传给后端自决
8. 自建 MCP（DIRECT_BACKEND / EXISTING_API）
   • tools/list、tools/call 结果形状按北向 era 输出；2.0 列表可带 ttlMs/cacheScope 等字段（有则填，无则省略）
   • OUT 包装逻辑按 era 分支错误码映射（如 resource missing -32002→-32602 仅对 modern）

Phase 2 — 南向 Dual-Era（网关 → 后端）

2A. Publisher 发现客户端

改造 MCPInitializerAndToolFetcher：

1. 构造/方法增加 protocolVersion 参数（来自校验请求或已存 metadata）
2. 1.0 路径：保持 initialize → 读 Mcp-Session-Id → notifications/initialized → tools/list + MCP-Protocol-Version
3. 2.0 路径：发送 MCP-Protocol-Version: 2026-07-28 + Mcp-Method；用 server/discover（若后端支持）或直接 tools/list；body 带 _meta；不依赖 session
4. 校验/刷新入口（McpServersApiServiceImpl / RestApiPublisherUtils）写入探测到的实际版本到 metadata.protocolVersion

2B. SERVER_PROXY 运行时

1. Synapse 透传保证不剥离：MCP-Protocol-Version、Mcp-Session-Id（1.0）、Mcp-Method/Mcp-Name（2.0）、以及 JSON body _meta
2. 从订阅/API 元数据读取后端 protocolVersion 注入 MessageContext（需确认 keymgt API 实体是否带 metadata；若无，在网关 DataHolder/部署产物中补充 protocolVersion 字段）
3. 同世代：透传（现逻辑），tools/list 仍可由网关用已发布目录合成（保持现行为）
4. 跨世代转译（新模块，建议 MCPProtocolTranslator）

Session 缓存：按 apiId + clientCredential/hash 短 TTL 内存/Redis（本方案优先 本地 Guava/Caffeine 式缓存 + TTL，与现有 gateway 缓存模式对齐；多节点后续再上分布式）。

2C. 自建 MCP 南向

DIRECT_BACKEND / EXISTING_API 的 tools/call→REST 与 MCP 版本无关；仅保证北向应答符合客户端 era（Phase 1）。

Phase 3 — 横切：鉴权、限流、分析、CORS

1. ThrottleHandler：继续仅对 tools/call 限流；method 来源含 Mcp-Method
2. Analytics：填充 MCP_PROTOCOL_VERSION / era / sessionId（legacy）到 SynapseAnalyticsDataProvider custom props
3. APIKeyValidator：tool→resource 映射不因 era 改变
4. WWW-Authenticate / well-known：保持；核对 2.0 对 iss 的更严校验不破坏现有 metadata 响应

Phase 4 — 测试与验收矩阵

单测重点：MCPUtils 协商/校验、MCPProtocolTranslator 往返、MCPInitializerAndToolFetcher 双路径、Throttle method 头解析。

主要改动文件（按优先级）

1. APIConstants.java — 版本/方法/头
2. 新建 MCPProtocolNegotiator + MCPProtocolTranslator（gateway 包下）
3. McpInitHandler.java / MCPUtils.java / MCPPayloadGenerator.java / McpMediator.java
4. MCPInitializerAndToolFetcher.java + Publisher validate/create/refresh 调用链
5. APIMappingUtil / CORS / metadata 校验
6. Throttle + Analytics providers
7. 对应 unit tests

不在本清单：Helm chart、Devportal UI 大改、完整 MCP Apps/Tasks 扩展（仅保证 core tools/list/call/discover/initialize）。

网关如何知道后端mcp是哪个版本

靠的是 MCP Server 上配置的 protocolVersion（表示南向后端协议），不是每次请求去猜后端。

数据从哪来

1. 创建/更新时写入
   Publisher 在 MCP Server DTO 里带 protocolVersion：

   • 2025-06-18 → 后端是 MCP 1.0
   • 2026-07-28 → 后端是 MCP 2.0
   • 不填则默认 2025-06-18

2. 落库
   写到 AM_API_METADATA，key 为 protocolVersion。

3. 部署到网关
   打进 Gateway 部署产物的 additionalProperties，运行时挂到 keymgt API.protocolVersion / apiProperties。

4. 请求时读取
   MCPProtocolNegotiator.resolveBackendProtocolVersion(api) 读这个字段，写入 MCP_BACKEND_PROTOCOL_VERSION，再和北向探测到的客户端版本比较，决定透传还是转译。

flowchart LR Pub[Publisher配置protocolVersion] DB[AM_API_METADATA] Deploy[Gateway部署产物] Runtime[Negotiator读后端版本] Pub --> DB --> Deploy --> Runtime

和北向的区别

运维时怎么填

• 明确后端是 1.0 / 2.0：创建 MCP Server 时设对 protocolVersion
• 校验第三方 MCP：先按 1.0 拉 tools，失败再试 2.0（validateThirdPartyMCPServer）；成功后建议把对应版本写回该 Server 的 protocolVersion

结论： 网关“知道”后端是几，是因为你（或校验流程）把它记在 MCP Server 配置里，并随部署带到网关；运行时只读配置，不做握手探测。