MCP Streamable HTTP 传输层实战：下一代 AI 工具通信协议完整指南

2025 年 3 月，MCP（Model Context Protocol）规范发布了 2025-03-26 版本，其中一个最重要的变更是引入了 Streamable HTTP 传输层，正式取代了此前基于 SSE（Server-Sent Events）的 HTTP 传输方案。这一变更彻底改变了 MCP Server 的部署架构——从需要维护长连接的有状态服务，演进为可水平扩展的无状态 HTTP 服务。如果你正在构建或维护 MCP Server，理解 Streamable HTTP 不是可选项，而是必修课。

🔌 一、为什么 MCP 要从 SSE 迁移到 Streamable HTTP

1.1 旧版 SSE 传输的核心痛点

在 2024-11-05 版本的 MCP 规范中，HTTP 传输层基于两个独立的端点：

• POST /messages — 客户端向服务端发送 JSON-RPC 请求
• GET /sse — 客户端通过 SSE 长连接接收服务端的响应和通知

这种设计存在三个致命问题：

⚠️ **警告：**SSE 传输在生产环境中最常遇到的问题是——Nginx/Cloudflare 等反向代理默认会缓冲 SSE 响应，导致客户端收不到实时消息。你需要手动配置 proxy_buffering off 和 X-Accel-Buffering: no 头。

1.2 Streamable HTTP 的设计哲学

Streamable HTTP 的核心思想是：用标准 HTTP POST 完成所有通信，响应可以是普通 JSON 也可以是 SSE 流。

客户端 → 服务端：始终使用 POST /mcp 端点发送 JSON-RPC 消息

服务端 → 客户端：响应 Content-Type 可以是 application/json（单条响应）或 text/event-stream（流式响应），由服务端按需决定

这种设计带来了几个关键优势：

• ✅ 无状态可扩展 — 每个请求都是独立的 HTTP 请求，天然支持负载均衡
• ✅ 标准 HTTP 认证 — 直接使用 Authorization 头，兼容 OAuth 2.1
• ✅ Serverless 友好 — 无需维持长连接，完美适配 Cloudflare Workers / AWS Lambda
• ✅ 浏览器原生支持 — 使用 fetch() API，无需 EventSource

1.3 传输方案对比

⚡ **关键结论：**如果你的 MCP Server 需要对外提供服务（无论是给 Claude、Cursor 还是自研 Agent），Streamable HTTP 是唯一正确的选择。stdio 只适合本地开发工具，SSE 已被官方标记为 deprecated。

🛠 二、Streamable HTTP 协议详解与 TypeScript 实现

2.1 协议握手流程

Streamable HTTP 的通信流程如下：

客户端                              服务端
  │                                   │
  │  POST /mcp                        │
  │  Content-Type: application/json   │
  │  Accept: application/json,        │
  │          text/event-stream        │
  │  Body: {"jsonrpc":"2.0",          │
  │         "method":"initialize",...}│
  │ ────────────────────────────────► │
  │                                   │
  │  200 OK                           │
  │  Content-Type: text/event-stream  │
  │  Mcp-Session-Id: abc123           │
  │  Body: SSE stream                 │
  │ ◄──────────────────────────────── │

关键请求头说明：

• Accept — 客户端必须声明支持 application/json 和 text/event-stream
• Mcp-Session-Id — 服务端返回的会话标识符，客户端后续请求必须携带
• Last-Event-ID — 用于断线重连时的消息恢复

2.2 构建 Streamable HTTP MCP Server

下面是完整的 TypeScript 实现，基于 Express 框架：

// MCP Streamable HTTP Server 核心实现
import express from 'express'
import { randomUUID } from 'node:crypto'
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js'
import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js'

const app = express()
app.use(express.json())

// 存储活跃的会话传输实例
const transports: Map<string, StreamableHTTPServerTransport> = new Map()

// MCP Streamable HTTP 端点 —— 所有请求都走这一个路由
app.all('/mcp', async (req, res) => {
  // 解析请求中的 Session ID
  const sessionId = req.headers['mcp-session-id'] as string | undefined
  let transport: StreamableHTTPServerTransport

  if (sessionId && transports.has(sessionId)) {
    // 已有会话，复用传输实例
    transport = transports.get(sessionId)!
  } else if (!sessionId && isInitializeRequest(req.body)) {
    // 新会话初始化请求
    transport = new StreamableHTTPServerTransport({
      sessionIdGenerator: () => randomUUID(),
      onsessioninitialized: (id) => {
        transports.set(id, transport)
        console.log(`Session initialized: ${id}`)
      }
    })

    // 创建 MCP Server 实例并注册工具
    const server = new McpServer({
      name: 'my-mcp-server',
      version: '1.0.0'
    })

    // 注册一个示例工具：JSON 格式化
    server.tool(
      'format_json',
      '格式化 JSON 字符串，支持缩进配置',
      {
        json: { type: 'string', description: '要格式化的 JSON 字符串' },
        indent: { type: 'number', description: '缩进空格数', default: 2 }
      },
      async ({ json, indent = 2 }) => {
        try {
          const parsed = JSON.parse(json)
          const formatted = JSON.stringify(parsed, null, indent)
          return { content: [{ type: 'text', text: formatted }] }
        } catch (e) {
          return {
            content: [{ type: 'text', text: `JSON 解析错误: ${(e as Error).message}` }],
            isError: true
          }
        }
      }
    )

    // 注册一个示例工具：JSON Schema 验证
    server.tool(
      'validate_json',
      '使用 JSON Schema 验证 JSON 数据',
      {
        data: { type: 'string', description: '待验证的 JSON 数据' },
        schema: { type: 'string', description: 'JSON Schema 定义' }
      },
      async ({ data, schema }) => {
        try {
          const parsedData = JSON.parse(data)
          const parsedSchema = JSON.parse(schema)
          // 这里应使用 Ajv 等库进行实际验证
          const isValid = typeof parsedData === 'object'
          return {
            content: [{
              type: 'text',
              text: isValid ? '✅ 验证通过' : '❌ 验证失败'
            }]
          }
        } catch (e) {
          return {
            content: [{ type: 'text', text: `错误: ${(e as Error).message}` }],
            isError: true
          }
        }
      }
    )

    // 连接 Server 和 Transport
    await server.connect(transport)

    // 会话关闭时清理资源
    transport.onclose = () => {
      if (transport.sessionId) {
        transports.delete(transport.sessionId)
        console.log(`Session closed: ${transport.sessionId}`)
      }
    }
  } else {
    // 无效请求
    res.status(400).json({
      jsonrpc: '2.0',
      error: { code: -32000, message: 'Bad Request: 无效的 MCP 会话' },
      id: null
    })
    return
  }

  // 将 HTTP 请求交给 Transport 处理
  await transport.handleRequest(req, res, req.body)
})

// 处理 Session 清理
app.delete('/mcp', async (req, res) => {
  const sessionId = req.headers['mcp-session-id'] as string | undefined
  if (sessionId && transports.has(sessionId)) {
    const transport = transports.get(sessionId)!
    await transport.close()
    transports.delete(sessionId)
  }
  res.status(200).end()
})

app.listen(3001, () => {
  console.log('MCP Streamable HTTP Server running on http://localhost:3001/mcp')
})

💡 **提示：**注意 app.all('/mcp') 使用了 all 方法——Streamable HTTP 规范要求同一个端点同时处理 POST（发送消息）和 GET（建立 SSE 流用于服务端推送通知）请求。

2.3 消息类型与响应格式

Streamable HTTP 中，服务端对客户端 POST 请求有两种响应模式：

单条 JSON 响应（适用于快速完成的工具调用）：

HTTP/1.1 200 OK
Content-Type: application/json
Mcp-Session-Id: abc123

{"jsonrpc":"2.0","id":1,"result":{"content":[{"type":"text","text":"done"}]}}

SSE 流式响应（适用于长时间运行的工具或需要进度报告的场景）：

HTTP/1.1 200 OK
Content-Type: text/event-stream
Mcp-Session-Id: abc123

id: 1
event: message
data: {"jsonrpc":"2.0","method":"notifications/progress","params":{"progress":50}}

id: 2
event: message
data: {"jsonrpc":"2.0","id":1,"result":{"content":[{"type":"text","text":"done"}]}}

💡 **提示：**服务端可以根据工具的执行时间动态选择响应格式——简单工具直接返回 JSON，复杂工具返回 SSE 流。客户端无需提前声明偏好，通过 Accept 头同时声明两种支持即可。

2.4 客户端连接实现

使用官方 SDK 的客户端实现：

// MCP Streamable HTTP 客户端连接
import { Client } from '@modelcontextprotocol/sdk/client/index.js'
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js'

async function main() {
  // 创建客户端实例
  const client = new Client({
    name: 'my-mcp-client',
    version: '1.0.0'
  })

  // 创建 Streamable HTTP 传输层
  const transport = new StreamableHTTPClientTransport(
    new URL('http://localhost:3001/mcp'),
    {
      // 可选：自定义请求头（如认证 Token）
      requestInit: {
        headers: {
          'Authorization': 'Bearer your-token-here'
        }
      }
    }
  )

  // 建立连接（自动完成 initialize 握手）
  await client.connect(transport)
  console.log('Connected to MCP server!')

  // 列出可用工具
  const tools = await client.listTools()
  console.log('Available tools:', tools.tools.map(t => t.name))

  // 调用工具
  const result = await client.callTool({
    name: 'format_json',
    arguments: {
      json: '{"name":"test","items":[1,2,3]}',
      indent: 4
    }
  })
  console.log('Result:', result.content)

  // 断开连接
  await client.close()
}

main().catch(console.error)

📌 **记住：**客户端无需手动管理 Mcp-Session-Id——SDK 的 StreamableHTTPClientTransport 会自动从初始化响应头中提取并附加到后续请求。

🚀 三、生产部署与避坑指南

3.1 Nginx 反向代理配置

Streamable HTTP 虽然基于标准 HTTP，但在反向代理后面仍需注意一些配置：

# Nginx 反向代理配置 —— MCP Streamable HTTP
server {
    listen 443 ssl;
    server_name mcp.example.com;

    location /mcp {
        proxy_pass http://127.0.0.1:3001;

        # 必须：禁用响应缓冲以支持 SSE 流式响应
        proxy_buffering off;

        # 必须：传递客户端真实 IP 和认证头
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # 必须：支持 DELETE 方法（Session 关闭）
        proxy_method $request_method;

        # 推荐：增加超时时间以支持长时间运行的工具调用
        proxy_read_timeout 300s;
        proxy_send_timeout 300s;

        # 推荐：禁用 Nginx 的响应缓冲头
        proxy_set_header X-Accel-Buffering no;
    }
}

⚠️ **警告：**最常见的部署错误是忘记 proxy_buffering off——这会导致 SSE 事件被 Nginx 缓冲，客户端收不到实时响应，调试时表现为 “initialize 成功但收不到工具调用结果”。

3.2 多实例部署与 Session 一致性

Streamable HTTP 的无状态特性使得水平扩展变得简单，但有一个关键细节：如果使用了 sessionIdGenerator（即有状态模式），所有请求必须路由到同一个后端实例。

有三种解决方案：

最理想的方案是完全无状态——不使用 sessionIdGenerator，让每次请求都是独立的：

// 无状态 MCP Server —— 不维护 Session
const transport = new StreamableHTTPServerTransport({
  // 不传 sessionIdGenerator，每次请求独立处理
  sessionIdGenerator: undefined,
})

💡 **提示：**无状态模式下，服务端无法主动向客户端推送通知（如进度更新）。如果你的工具需要长时间运行并报告进度，建议使用有状态模式配合 Redis 存储 Session 映射。

3.3 认证与 OAuth 2.1 集成

Streamable HTTP 天然支持标准 HTTP 认证。MCP 规范推荐使用 OAuth 2.1：

// MCP Server 认证中间件
import { createRemoteJWKSet, jwtVerify } from 'jose'

const JWKS = createRemoteJWKSet(
  new URL('https://auth.example.com/.well-known/jwks.json')
)

// Express 认证中间件
async function authMiddleware(req: express.Request, res: express.Response, next: express.NextFunction) {
  // 初始化请求（initialize）不需要认证
  if (isInitializeRequest(req.body)) {
    return next()
  }

  const authHeader = req.headers.authorization
  if (!authHeader?.startsWith('Bearer ')) {
    res.status(401).json({
      jsonrpc: '2.0',
      error: { code: -32001, message: 'Unauthorized: 缺少 Bearer Token' },
      id: null
    })
    return
  }

  try {
    const token = authHeader.slice(7)
    const { payload } = await jwtVerify(token, JWKS, {
      issuer: 'https://auth.example.com',
      audience: 'mcp-server'
    })
    // 将用户信息挂载到请求对象上
    (req as any).userId = payload.sub
    next()
  } catch (e) {
    res.status(401).json({
      jsonrpc: '2.0',
      error: { code: -32001, message: 'Unauthorized: Token 无效或已过期' },
      id: null
    })
  }
}

app.all('/mcp', authMiddleware, async (req, res) => {
  // ... 正常处理逻辑
})

3.4 错误处理与断线重连

Streamable HTTP 支持通过 Last-Event-ID 实现消息重放。当客户端断线重连时，可以请求服务端重发丢失的消息：

// 服务端：实现消息重放缓存
class MessageReplayBuffer {
  private buffer: Map<number, { id: number; event: string; data: string }> = new Map()
  private maxSize = 100
  private sequence = 0

  add(event: string, data: string) {
    const id = ++this.sequence
    this.buffer.set(id, { id, event, data })
    // 超出容量时清理最旧的消息
    if (this.buffer.size > this.maxSize) {
      const oldest = this.buffer.keys().next().value
      this.buffer.delete(oldest)
    }
    return id
  }

  // 获取指定 ID 之后的所有消息，用于断线重连
  replayFrom(lastId: number): Array<{ id: number; event: string; data: string }> {
    const messages: Array<{ id: number; event: string; data: string }> = []
    for (const [id, msg] of this.buffer) {
      if (id > lastId) {
        messages.push(msg)
      }
    }
    return messages
  }
}

3.5 性能基准对比

以下是 Streamable HTTP 与旧版 SSE 传输在同一硬件环境下的对比测试数据：

⚡ **关键结论：**Streamable HTTP 在并发能力和内存占用上有巨大优势。旧版 SSE 的每个连接都占用一个 goroutine/thread，而 Streamable HTTP 的请求是短暂的，处理完即释放。

3.6 常见踩坑点

基于实际生产经验，以下是开发者最容易踩的坑：

• ❌ 坑 1：忘记设置 Accept 头 — 客户端请求必须声明 Accept: application/json, text/event-stream，否则服务端不知道客户端支持什么格式
• ❌ 坑 2：在无状态模式下使用通知 — 无状态模式不支持服务端主动推送，server.notification() 调用会静默失败
• ❌ 坑 3：Nginx 缓冲 SSE — 如前所述，必须配置 proxy_buffering off
• ❌ 坑 4：Session ID 传递错误 — Mcp-Session-Id 是小写 HTTP 头，不是 query 参数
• ❌ 坑 5：忽略 DELETE 端点 — 客户端断开时需要调用 DELETE /mcp 清理服务端资源，否则会导致内存泄漏

⚠️ **警告：**如果你使用的是 @modelcontextprotocol/sdk 的早期版本（< 1.12.0），可能还没有 Streamable HTTP 支持。请确保升级到最新版本。

💡 四、最佳实践总结

4.1 选型决策树

你的 MCP Server 需要部署在哪里？
│
├─ 本地 CLI 工具 / IDE 插件
│  └─ 使用 stdio 传输 ✅
│
├─ 内部服务 / 开发环境
│  └─ Streamable HTTP（无状态模式）✅
│
├─ 对外 API 服务 / 生产环境
│  ├─ 需要服务端通知/进度？
│  │  ├─ 是 → Streamable HTTP（有状态 + Redis）✅
│  │  └─ 否 → Streamable HTTP（无状态）✅
│  └─ 需要 Serverless 部署？
│     └─ Streamable HTTP（无状态 + Cloudflare Workers）✅
│
└─ 浏览器端 MCP Client
   └─ Streamable HTTP（fetch API）✅

4.2 关键要点

1. 新项目直接使用 Streamable HTTP — 不要再使用 SSE 传输，它已被标记为 deprecated
2. 优先选择无状态模式 — 除非你明确需要服务端推送通知
3. 正确配置反向代理 — proxy_buffering off 是必须的
4. 使用 OAuth 2.1 认证 — Streamable HTTP 天然支持标准 HTTP 认证
5. 实现断线重连 — 利用 Last-Event-ID 实现消息重放

4.3 相关工具推荐

Streamable HTTP 是 MCP 协议迈向生产级的重要一步。它让 MCP Server 的部署从 “需要精心维护的长连接服务” 变成了 “标准的 HTTP API 服务”，这与整个云原生架构的趋势完全一致。如果你正在构建 AI Agent 的工具层，现在就迁移到 Streamable HTTP。