MCP 无状态化与迁移

握手消失：身份与能力从连接级降到请求级

以前"连上问一次"，现在"每次都带着"——于是任何请求可以落到任何实例。

// 背景与原理

旧协议的生命周期是：连接 → initialize 交换协议版本与 capability → initialized → 后续请求靠 Mcp-Session-Id 认回同一会话。这套设计让 server 有权假设"同一 session 的请求我见过前因"，代价是横向扩容必须有粘性：要么 LB 按 session 粘住实例，要么把会话态放进 Redis 之类的共享存储。

新规范（SEP-2575 / SEP-2567）把这一层整个删掉。客户端身份改为每个请求都在 _meta 里自带，键名是固定的反向域名 io.modelcontextprotocol/clientInfo；能力发现变成一个可选的 server/discover 方法——客户端"需要提前知道"时才调，而不是作为任何调用的前置。配套的还有 W3C Trace Context（SEP-414）也走 _meta，键名固定为 traceparent / tracestate / baggage，这是第一次让 MCP 调用链能直接并进你现有的 OTel 链路。

// 实战示例

// 新协议：一个自足的 tools/call，没有前置握手
{
  "jsonrpc": "2.0", "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search",
    "arguments": { "q": "mcp stateless" },
    "_meta": {
      "io.modelcontextprotocol/clientInfo": { "name": "my-app", "version": "1.0" }
    }
  }
}

// TypeScript SDK v2：工厂函数每请求建一个 server 实例
import { createMcpHandler, McpServer } from '@modelcontextprotocol/server';

const handler = createMcpHandler(() => {
  const server = new McpServer(
    { name: 'my-server', version: '1.0.0' },
    { capabilities: { tools: {} } }
  );
  // 在这里注册 tools / resources / prompts
  return server;
});
export default handler;  // Web 标准运行时直接导出

Mcp-Method / Mcp-Name：把路由信息抬到 HTTP 头

网关不该为了做限流去解 JSON-RPC body——现在它不用了。

// 背景与原理

旧协议下所有 MCP 流量在 HTTP 层长得一模一样：同一个 POST /mcp，方法名和工具名埋在 body 里。想按工具做限流、按方法做鉴权、在 WAF 上拦某个危险操作，都得让网关去解 JSON body——这在基础设施层是个难看且易错的活。

SEP-2243 把这件事规范化：Streamable HTTP 请求必须带 MCP-Protocol-Version、Mcp-Method、Mcp-Name 三个头。Mcp-Method 是 JSON-RPC 方法名；Mcp-Name 镜像 params.name 或 params.uri，于是点名目标的调用（tools/call / resources/read / prompts/get）在头里就暴露了"要动哪个东西"。关键是这不是善意提示：server 必须校验头与 body 一致，不一致就拒——TS SDK 的实现是 HTTP 400 配错误码 -32020（HeaderMismatch）。工具还可在 inputSchema 里用 x-mcp-header 标记参数，SDK 会把它序列化成 Mcp-Param-{Name} 头（必要时 Base64）。

// 实战示例

# 手写请求：三个头缺一个就是协议错误
curl -X POST https://example.com/mcp \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'Mcp-Method: tools/call' \
  -H 'Mcp-Name: search' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"search","arguments":{"q":"x"}}}'

# 现在才能在网关层这样写（Envoy 风格，按工具分桶限流）
# descriptor: request_headers -> Mcp-Name -> rate_limit
# 贵的工具（跑 SQL / 调外部 API）单独一个更紧的桶，
# 便宜的 tools/list 走宽桶 —— 不碰 body 一行。

MRTR：用重试代替长连接

工具执行中途要问用户，不再需要一条活着的服务端连接——把状态签个名交给客户端拿回来。

// 背景与原理

"工具跑一半需要用户确认/补参数"这个需求，旧协议靠 server 在 SSE 流上主动发请求实现。这是粘性会话的最后一个硬依赖：server 必须在那条连接上活着，连接断了流程就死了，也因此无法跨实例。

SEP-2322 引入 MRTR（Multi-Round-Trip Requests）把这件事翻过来：server 不主动推，而是直接返回一个"我还需要输入"的结果——resultType: 'input_required'，带 inputRequests（要问什么）与 requestState（不透明字符串，装着继续执行所需的上下文）；客户端收齐答案后重试原调用，答案放进 inputResponses、requestState 原样带回。流程状态于是在两跳之间寄存在客户端手里，server 不需要记住任何东西，下一跳落到别的实例也能续上。配套的 SEP-2260 收紧了残留的服务端发起请求：只允许在 server 正在处理某个客户端请求期间发出。

// 实战示例

// TS SDK v2：requestState 必须签名（HMAC-SHA256）
import { inputRequired, acceptedContent,
         createRequestStateCodec } from '@modelcontextprotocol/server';

const stateCodec = createRequestStateCodec<FlowState>({ key: SECRET });

async (args, ctx) => {
  const state = ctx.mcpReq.requestState<FlowState>();
  if (!state) {                      // 第一跳：问
    return inputRequired({
      inputRequests: { count: inputRequired.elicit({ /* schema */ }) },
      requestState: await stateCodec.mint({ phase: 'awaiting-count' })
    });
  }
  // 第二跳：取答案继续（可能落在另一个实例上）
  const response = acceptedContent(ctx.mcpReq.inputResponses, 'count', SCHEMA);
}

缓存作用域、CIMD 与 12 个月窗口：迁移清单

这一版给了你两个新的脚枪：标错的缓存作用域，和一个会替你发 HTTP 请求的授权服务器。

// 背景与原理

无状态化之后，客户端重复拉 tools/list 的成本浮上来了，于是 SEP-2549 给 list 与 resource 结果加了仿 HTTP Cache-Control 的 ttlMs 与 cacheScope。TS SDK 的默认值是最保守的 ttlMs: 0 / cacheScope: 'private'——这个默认是对的，把它改成 'shared' 之前要能证明该结果与调用者身份无关。

授权侧两条变化更需要主动动手。其一，Dynamic Client Registration（DCR）被正式弃用，转向 CIMD（Client ID Metadata Documents）：客户端的 client_id 变成一个 URL，授权服务器首次见到时去 fetch 该 URL 拿元数据文档。动机是 DCR 的开放注册被用来注册钓鱼客户端（2025 年有公开的一键账号接管案例），CIMD 把客户端身份绑到一个它必须真正控制的域名上。其二，SEP-2468 要求按 RFC 9207 校验授权响应里的 iss 参数。

弃用节奏由 SEP-2577 定规矩：Active / Deprecated / Removed 三段，弃用到最早可能移除之间至少十二个月。本版被标弃用的是 Roots、Sampling、Logging 与旧的 HTTP+SSE transport——方法、类型与 capability 标志在本版及此后一年内发布的每个版本中都继续可用。SDK 侧：TypeScript、Python、Go、C# 四个 Tier 1 SDK 均已支持 2026-07-28，Rust 为 beta。

// 实战示例

// 缓存提示：改 'shared' 前先问"这个 list 会按用户过滤吗"
new McpServer({ name: 'my-server', version: '1.0.0' }, {
  capabilities: { tools: {} },
  cacheHints: { tools: { ttlMs: 3600000, cacheScope: 'shared' } }
  // ↑ 仅当工具清单对所有调用者完全相同时才成立
});

# 自建 server 迁移清单
1. 升到支持 2026-07-28 的 SDK（TS/Python/Go/C# 已 GA，Rust beta）
2. 入口换成无状态 handler（TS: createMcpHandler）；删掉 initialize 分支
3. 审一遍进程内状态：per-session 缓存 / 累积 scope → 外置或去掉
4. 验证 Mcp-Method / Mcp-Name 能穿透你的反代与 CDN
5. 服务端发起请求 → 改写成 MRTR；requestState 必须签名
6. 给每个 list 显式标 ttlMs / cacheScope，默认留 private
7. 授权：加 RFC 9207 iss 校验；规划 DCR → CIMD
8. 盘点对 Roots / Sampling / Logging 的依赖（约一年窗口）
9. 旧客户端：SDK 的 legacy 'stateless' 模式可同端点兼容 2025 流量