ModelContextProtocol TypeScript SDK 中 StreamableHTTPServerTransport 初始化问题解析

问题背景

在使用 ModelContextProtocol (MCP) TypeScript SDK 开发基于 HTTP 的 RPC 服务时，开发者可能会遇到一个常见的初始化错误："Bad Request: Server not initialized"。这个问题主要出现在使用 StreamableHTTPServerTransport 组件时，无论是状态还是无状态模式。

问题现象

开发者在使用 Express 框架搭建 MCP 服务器时，当客户端发送初始化请求后，服务器返回以下错误响应：

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32000,
    "message": "Bad Request: Server not initialized"
  },
  "id": null
}

根本原因分析

经过深入分析，这个问题主要由以下几个因素导致：

1. 初始化参数不完整：MCP 协议要求初始化请求必须包含完整的参数对象，包括协议版本、客户端能力和客户端信息。许多开发者只发送空的 params 对象，导致服务器无法完成初始化。

2. CORS 限制：在浏览器环境中运行时，由于跨域资源共享(CORS)限制，浏览器可能无法读取响应头中的 mcp-session-id，导致后续请求无法携带正确的会话标识。

3. 会话管理逻辑缺陷：示例代码中的会话ID处理存在逻辑错误，使用位或运算符(|)而不是逻辑或(||)，导致会话ID无法正确获取。

解决方案

1. 完善初始化请求

正确的初始化请求应该包含以下完整参数：

{
  "jsonrpc": "2.0",
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {
      "name": "example-client",
      "version": "1.0.0"
    }
  },
  "id": 0
}

2. 处理 CORS 问题

对于浏览器客户端，需要在服务器响应中添加以下头部：

res.setHeader('Access-Control-Expose-Headers', 'mcp-session-id');

这允许浏览器客户端读取 mcp-session-id 头部，以便在后续请求中携带正确的会话标识。

3. 修正会话管理代码

修正会话ID获取逻辑，使用正确的逻辑或运算符：

const sessionId = req.headers['mcp-session-id'] || undefined;

最佳实践建议

1. 完整的生命周期实现：确保按照 MCP 协议规范实现完整的生命周期管理，包括初始化、会话维持和终止。

2. 错误处理：增强错误处理逻辑，为客户端提供更明确的错误信息，帮助快速定位问题。

3. 会话超时机制：实现会话超时机制，自动清理长时间不活动的会话，释放服务器资源。

4. 协议版本兼容性：在初始化参数中明确指定协议版本，确保客户端和服务器使用兼容的协议版本进行通信。

总结

MCP TypeScript SDK 中的 StreamableHTTPServerTransport 初始化问题通常是由于不完整的初始化参数或跨域限制导致的。通过遵循协议规范、完善初始化请求参数和处理 CORS 限制，可以有效地解决这些问题。开发者应当仔细阅读协议文档，确保实现符合规范，同时考虑各种运行环境下的兼容性问题。