MCP Inspector中Streamable HTTP授权头缺失问题深度解析

还在为MCP服务器授权认证问题头疼吗？本文将深入剖析ModelContextProtocol（MCP）Inspector中Streamable HTTP传输协议的授权头缺失问题，帮你彻底解决认证难题！

📋 问题概述

MCP Inspector作为MCP服务器的调试工具，支持三种传输协议：STDIO、SSE（Server-Sent Events）和Streamable HTTP。然而在实际使用中，开发者发现Streamable HTTP连接无法正确传递Authorization（授权）头，导致认证失败。

🔍 技术根源分析

通过分析useConnection.ts源码，我们发现问题的核心在于：

SSE与Streamable HTTP的差异处理

在直接连接模式（direct connection）下，SSE和Streamable HTTP的请求头处理存在差异：

SSE连接（第500-522行）：

case "sse":
  requestHeaders["Accept"] = "text/event-stream";
  requestHeaders["content-type"] = "application/json";
  // 完整的授权头处理逻辑

Streamable HTTP连接（第524-554行）：

case "streamable-http":
  transportOptions = {
    fetch: async (url, init) => {
      requestHeaders["Accept"] = "text/event-stream, application/json";
      requestHeaders["Content-Type"] = "application/json";
      // 缺少授权头的特殊处理
    }
  };

授权头处理逻辑缺失

在useConnection.ts第441-461行的授权处理逻辑中，虽然为SSE连接正确添加了OAuth令牌，但Streamable HTTP连接未能充分利用这一机制：

if (needsOAuthToken) {
  const oauthToken = (await serverAuthProvider.tokens())?.access_token;
  if (oauthToken) {
    finalHeaders = [
      ...finalHeaders.filter((header) => !isEmptyAuthHeader(header)),
      {
        name: "Authorization",
        value: `Bearer ${oauthToken}`,
        enabled: true,
      },
    ];
  }
}

🎯 影响范围

传输类型	授权支持	影响程度
STDIO	✅ 完整支持	无影响
SSE	✅ 完整支持	无影响
Streamable HTTP	❌ 部分缺失	严重影响

💡 解决方案

临时解决方案

1. 使用代理模式连接：

   • 通过MCP Proxy中转，利用代理的认证机制
   • 配置见server/index.ts

2. 手动添加自定义头：

   • 在UI界面中手动配置Authorization头
   • 参考CustomHeaders.tsx

长期修复方案

代码层面需要统一SSE和Streamable HTTP的授权处理逻辑：

// 统一授权头处理
const applyAuthHeaders = (headers: HeadersInit, authToken?: string) => {
  if (authToken) {
    headers['Authorization'] = `Bearer ${authToken}`;
  }
  return headers;
};

// 在Streamable HTTP连接中应用
case "streamable-http":
  const authToken = await getAuthToken();
  applyAuthHeaders(requestHeaders, authToken);
  // ...其余逻辑

🚀 最佳实践

1. 优先使用SSE传输：目前SSE的授权支持最完善
2. 定期检查配置：使用configUtils.ts验证连接设置
3. 监控会话状态：关注[mcp-session-id]和协议版本头

📊 开发建议

对于MCP服务器开发者：

• 实现多种认证方式备用
• 提供清晰的错误日志
• 支持标准OAuth 2.0流程

对于工具使用者：

• 保持MCP Inspector版本更新
• 关注官方文档更新
• 参与社区问题反馈

MCP Inspector整体架构示意图

🔮 未来展望

随着MCP协议的不断发展，Streamable HTTP的授权支持将逐步完善。开发团队正在积极解决这一问题，预计在后续版本中提供完整的授权头支持。

通过本文的深度解析，相信您已经掌握了MCP Inspector中Streamable HTTP授权头问题的核心要点。无论是临时规避还是长期解决方案，都能帮助您更顺畅地进行MCP服务器开发和调试！