ModelContextProtocol TypeScript SDK 中 SSE 连接的自定义 Header 实现方案

背景介绍

在使用 ModelContextProtocol (MCP) 的 TypeScript SDK 时，开发者经常需要为服务器发送事件(SSE)连接添加自定义 Header，特别是用于身份验证的 API Token。这是一个常见的安全需求，但在浏览器环境中实现起来却存在技术限制。

核心问题分析

标准 Web API 中的 EventSource 接口存在一个重要的限制：它不支持在初始化时添加自定义 HTTP Header。这个限制源于 EventSource 的设计初衷是为了简化服务器推送事件的使用，但同时也牺牲了一些灵活性。

在 MCP TypeScript SDK 中，SSEClientTransport 类封装了 EventSource 的功能，用于建立与 MCP 服务器的 SSE 连接。当开发者需要为 /sse 和 /message 端点添加认证 Header 时，会遇到以下情况：

1. /message 端点可以正常使用自定义 Header，因为它是通过标准的 fetch API 实现的
2. /sse 端点则无法直接添加 Header，因为底层依赖的是 EventSource

Node.js 环境解决方案

对于 Node.js 运行时环境，我们可以利用 eventsource 这个第三方包来突破浏览器环境的限制。这个包提供了更灵活的 EventSource 实现，支持通过 fetch 拦截器添加自定义 Header。

具体实现方案如下：

import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse'
import { EventSource } from 'eventsource'

// 在全局对象上注册自定义 EventSource
globalThis.EventSource = EventSource

const transport = new SSEClientTransport(
  new URL('服务器地址'),
  {
    requestInit: {
      headers: { 'Authorization': 'Bearer <令牌>' }
    },
    eventSourceInit: {
      fetch(input, init) {
        const headers = new Headers(init?.headers || {})
        headers.set('Authorization', 'Bearer <令牌>')
        return fetch(input, {
          ...init,
          headers
        })
      }
    } as any  // 需要类型断言，因为这是非标准扩展
  }
)

关键实现细节

1. 全局覆盖 EventSource：我们需要用第三方实现替换原生的 EventSource
2. fetch 拦截器：通过提供自定义 fetch 方法，我们可以在 SSE 连接建立时注入 Header
3. 类型处理：由于这是非标准扩展，需要进行类型断言
4. Header 一致性：确保 SSE 和普通消息请求使用相同的认证信息

浏览器环境的限制

在纯浏览器环境中，目前还没有完美的解决方案。这是因为：

1. 浏览器原生 EventSource API 确实不支持自定义 Header
2. 所有基于 polyfill 的方案最终都会回退到原生 API
3. 安全限制阻止了通过其他方式注入 Header

对于必须在前端实现的场景，建议考虑以下替代方案：

1. 使用 WebSocket 替代 SSE
2. 通过 URL 参数传递认证令牌（安全性较低）
3. 设置专用的认证 cookie

最佳实践建议

1. 环境检测：在代码中区分 Node.js 和浏览器环境，提供不同的实现
2. 错误处理：完善错误捕获和重试机制，特别是对于认证失败的情况
3. 令牌管理：实现令牌刷新逻辑，避免使用过期令牌
4. 类型安全：为自定义配置创建明确的类型定义，避免滥用 any

总结

虽然浏览器环境的限制使得 SSE 连接添加自定义 Header 存在挑战，但在 Node.js 环境中我们已经有成熟的解决方案。理解这些技术限制和解决方案，有助于开发者更好地设计基于 MCP 协议的应用程序架构。随着 Web 标准的发展，未来可能会有更优雅的解决方案出现。