Supergateway：用一道命令打通 MCP 工具生态的"协议桥梁"

背景：MCP 的碎片化困境

2024年底，Anthropic 推出 Model Context Protocol（MCP）开放协议，旨在标准化 AI 模型与外部工具/数据的交互方式。很快，GitHub 上涌现出数百个 MCP 服务器实现——有人做了文件系统访问、有人做了 Git 操作、有人接了数据库……但问题随之而来：这些 MCP 服务器几乎清一色只支持 stdio 通信模式，而许多现代 AI 工具（如 Claude Desktop、Cursor 等）期望通过 SSE（Server-Sent Events）或 WebSocket 连接。

这就像一群说不同方言的人被困在同一个会议室——大家都有好东西要分享，却没办法直接交流。Supergateway 正是来解决这个问题的：它是一个 MCP 协议网关，用一道命令把 stdio 服务桥接到 SSE、WebSocket 或 Streamable HTTP，让任何 MCP 客户端都能无缝调用任意 MCP 服务器。

Supergateway Logo

图1：Supergateway 项目 Logo——运行 MCP stdio 服务器的 SSE/WebSocket 网关

Supergateway 由 Supercorp 团队开发维护，得到 Supermachine、Superinterface 等平台的支持。当前版本 3.4.3，GitHub 获得 2671 Stars，MIT 开源协议。

它到底能做什么？——四种桥接模式

Supergateway 支持 6 种传输方向，但核心价值可以用一句话概括：消除 MCP 服务器与 MCP 客户端之间的协议鸿沟。

1. stdio → SSE（最常用）

将本地 stdio MCP 服务器暴露为 SSE 服务。典型场景：你想通过 ngrok 把本地 MCP 服务器分享给远程 AI 客户端：

npx -y supergateway --stdio "npx -y @modelcontextprotocol/server-filesystem /path/to/folder" --port 8000

客户端通过 GET /sse 订阅事件，POST /message 发送请求。

2. SSE → stdio

连接远程 SSE MCP 服务器，在本地通过 stdio 输出。适合把云端托管的 MCP 服务接入本地命令行工具（如 MCP Inspector）：

npx -y supergateway --sse "https://your-remote-mcp-server.com/sse"

3. stdio → Streamable HTTP

将 stdio 服务器暴露为符合 MCP 新版 Streamable HTTP 传输协议的 HTTP 接口，支持无状态和有状态两种模式。有状态模式下支持会话超时管理，适合长时间运行的复杂工具调用：

# 无状态
npx -y supergateway --stdio "uvx mcp-server-fetch" --outputTransport streamableHttp --port 8000

# 有状态（会话模式）
npx -y supergateway --stdio "uvx mcp-server-git" --outputTransport streamableHttp --stateful --sessionTimeout 60000

4. stdio → WebSocket

对于需要双向实时通信的场景，Supergateway 也支持 WebSocket 模式，适合需要频繁交互的 AI 代理工作流。

5. Streamable HTTP → stdio

将支持新版 HTTP 传输协议的 MCP 服务器，通过 stdio 接入本地环境。

6. Claude Desktop / Cursor 集成

Supergateway 专门提供了 Claude Desktop 和 Cursor 的配置示例，通过 SSE → stdio 模式，让这些 AI IDE 能够调用远程 MCP 服务器：

{
  "mcpServers": {
    "remoteFilesystem": {
      "command": "npx",
      "args": ["-y", "supergateway", "--sse", "https://your-mcp-server.com"]
    }
  }
}

⚠️ 已知限制：Cursor 传递带空格的 Authorization Header 时有 Bug，官方建议使用 --oauth2Bearer 替代 --header 传 Authorization。

技术架构：TypeScript + Express，轻量而专注

Supergateway 的代码库非常干净，总共约 2,700 行 TypeScript 代码，零生产依赖，核心全自研：

依赖栈（仅 8 个）：

@modelcontextprotocol/sdk（MCP 协议实现）
express（HTTP 服务器）
ws（WebSocket）
yargs（CLI 参数解析）
cors（跨域支持）
body-parser、uuid、zod（工具库）

代码结构（模块化清晰）：

目录/文件	职责
`src/gateways/`	6 种传输转换核心逻辑（stdio↔SSE/WS/StreamableHttp）
`src/server/`	WebSocket 服务器封装
`src/lib/`	工具函数（CORS、日志、会话计数、信号处理）
`src/types.ts`	TypeScript 类型定义
`src/index.ts`	CLI 入口 + 参数路由

架构特点：

纯 ESM 模块（"type": "module"）
使用 Node.js 原生 Test Runner（node --test）进行测试，需 Node 24+
Prettier + Husky + lint-staged 强制代码格式化
多架构 Docker 构建（linux/amd64 + linux/arm64 via docker-bake.hcl）

部署：npx 秒上手，Docker 零依赖

Supergateway 的部署体验是它最大的亮点之一——零安装门槛：

方式一：npx（30 秒）

npx -y supergateway --stdio "uvx mcp-server-git"

前提：本地有 Node.js 环境（用于 npx），以及 MCP 服务器的命令行工具（如 uvx）。

方式二：Docker（推荐，零污染）

docker run -it --rm -p 8000:8000 supercorp/supergateway     --stdio "npx -y @modelcontextprotocol/server-filesystem /"

还提供三个预构建变体镜像，针对不同运行时需求：

镜像	内容	适用场景
`supercorp/supergateway`	Node.js + supergateway	基础场景
`supercorp/supergateway:uvx`	+ uv/uvx（Python 包运行器）	Python MCP 服务器（如 mcp-server-fetch）
`supercorp/supergateway:deno`	+ Deno	Deno 脚本类 MCP 服务器

部署难度：非常简单（1/5）

无需配置、无数据库、无环境变量
Docker 镜像自动多架构构建
默认 8000 端口，所有参数有默认值

硬件需求：极低

无 GPU 要求
RAM: ~512MB
磁盘: ~200MB（Node 基础镜像）

与同类工具对比

Supergateway 解决了 MCP 生态的一个关键痛点。类似的替代方案包括：

直接修改 MCP 服务器源码：工作量巨大，不可行
mcp-relay（类似项目）：功能较单一，不支持多传输模式
Cloudflare Workers 部署：需要额外学习成本

Supergateway 的优势在于极简部署 + 全面协议覆盖 + 开箱即用的 Claude/Cursor 集成。

局限与风险

无持久化 Web UI：纯 CLI 工具，调试依赖日志输出（--logLevel debug）
SSE → stdio 模式日志走 stderr：生产环境日志收集需注意
会话管理仅限 Streamable HTTP 有状态模式：SSE/WS 模式不支持会话
Cursor 的 Authorization Bug：需要绕道 --oauth2Bearer
ngrok 等内网穿透方案依赖外部服务：生产公网部署需自建反向代理

行业意义：MCP 生态的"黏合剂"

Supergateway 的价值不仅是技术层面的协议转换，更是生态层面的连接器。随着 MCP 协议被 Claude、Cursor、WindSurf、Cline 等主流 AI 编程工具广泛采用，如何快速集成第三方 MCP 服务器成为开发者最迫切的需求。Supergateway 让这个过程从"修改源码"变成"一条命令"，大幅降低了 MCP 生态的接入门槛。

项目自 2024 年 12 月上线以来持续活跃维护（最新更新 2025 年 10 月），已有来自全球的 25+ 位贡献者参与，累计 89 个 Pull Request，显示出良好的社区活跃度。随着 MCP 协议的演进（尤其是 Streamable HTTP 的推广），Supergateway 的传输模式覆盖度使其具备长期生命力。

分析基于 GitHub 仓库 v3.4.3（2025年10月）

Supergateway：用一道命令打通 MCP 工具生态的"协议桥梁"

背景：MCP 的碎片化困境

Supergateway Logo

图1：Supergateway 项目 Logo——运行 MCP stdio 服务器的 SSE/WebSocket 网关

Supergateway 由 Supercorp 团队开发维护，得到 Supermachine、Superinterface 等平台的支持。当前版本 3.4.3，GitHub 获得 2671 Stars，MIT 开源协议。

它到底能做什么？——四种桥接模式

Supergateway 支持 6 种传输方向，但核心价值可以用一句话概括：消除 MCP 服务器与 MCP 客户端之间的协议鸿沟。

1. stdio → SSE（最常用）

将本地 stdio MCP 服务器暴露为 SSE 服务。典型场景：你想通过 ngrok 把本地 MCP 服务器分享给远程 AI 客户端：

npx -y supergateway --stdio "npx -y @modelcontextprotocol/server-filesystem /path/to/folder" --port 8000

客户端通过 GET /sse 订阅事件，POST /message 发送请求。

2. SSE → stdio

连接远程 SSE MCP 服务器，在本地通过 stdio 输出。适合把云端托管的 MCP 服务接入本地命令行工具（如 MCP Inspector）：

npx -y supergateway --sse "https://your-remote-mcp-server.com/sse"

3. stdio → Streamable HTTP

# 无状态
npx -y supergateway --stdio "uvx mcp-server-fetch" --outputTransport streamableHttp --port 8000

# 有状态（会话模式）
npx -y supergateway --stdio "uvx mcp-server-git" --outputTransport streamableHttp --stateful --sessionTimeout 60000

4. stdio → WebSocket

对于需要双向实时通信的场景，Supergateway 也支持 WebSocket 模式，适合需要频繁交互的 AI 代理工作流。

5. Streamable HTTP → stdio

将支持新版 HTTP 传输协议的 MCP 服务器，通过 stdio 接入本地环境。

6. Claude Desktop / Cursor 集成

Supergateway 专门提供了 Claude Desktop 和 Cursor 的配置示例，通过 SSE → stdio 模式，让这些 AI IDE 能够调用远程 MCP 服务器：

{
  "mcpServers": {
    "remoteFilesystem": {
      "command": "npx",
      "args": ["-y", "supergateway", "--sse", "https://your-mcp-server.com"]
    }
  }
}

⚠️ 已知限制：Cursor 传递带空格的 Authorization Header 时有 Bug，官方建议使用 --oauth2Bearer 替代 --header 传 Authorization。

技术架构：TypeScript + Express，轻量而专注

Supergateway 的代码库非常干净，总共约 2,700 行 TypeScript 代码，零生产依赖，核心全自研：

依赖栈（仅 8 个）：

@modelcontextprotocol/sdk（MCP 协议实现）
express（HTTP 服务器）
ws（WebSocket）
yargs（CLI 参数解析）
cors（跨域支持）
body-parser、uuid、zod（工具库）

代码结构（模块化清晰）：

目录/文件	职责
`src/gateways/`	6 种传输转换核心逻辑（stdio↔SSE/WS/StreamableHttp）
`src/server/`	WebSocket 服务器封装
`src/lib/`	工具函数（CORS、日志、会话计数、信号处理）
`src/types.ts`	TypeScript 类型定义
`src/index.ts`	CLI 入口 + 参数路由

架构特点：

纯 ESM 模块（"type": "module"）
使用 Node.js 原生 Test Runner（node --test）进行测试，需 Node 24+
Prettier + Husky + lint-staged 强制代码格式化
多架构 Docker 构建（linux/amd64 + linux/arm64 via docker-bake.hcl）

部署：npx 秒上手，Docker 零依赖

Supergateway 的部署体验是它最大的亮点之一——零安装门槛：

方式一：npx（30 秒）

npx -y supergateway --stdio "uvx mcp-server-git"

前提：本地有 Node.js 环境（用于 npx），以及 MCP 服务器的命令行工具（如 uvx）。

方式二：Docker（推荐，零污染）

docker run -it --rm -p 8000:8000 supercorp/supergateway     --stdio "npx -y @modelcontextprotocol/server-filesystem /"

还提供三个预构建变体镜像，针对不同运行时需求：

镜像	内容	适用场景
`supercorp/supergateway`	Node.js + supergateway	基础场景
`supercorp/supergateway:uvx`	+ uv/uvx（Python 包运行器）	Python MCP 服务器（如 mcp-server-fetch）
`supercorp/supergateway:deno`	+ Deno	Deno 脚本类 MCP 服务器

部署难度：非常简单（1/5）

无需配置、无数据库、无环境变量
Docker 镜像自动多架构构建
默认 8000 端口，所有参数有默认值

硬件需求：极低

无 GPU 要求
RAM: ~512MB
磁盘: ~200MB（Node 基础镜像）

与同类工具对比

Supergateway 解决了 MCP 生态的一个关键痛点。类似的替代方案包括：

直接修改 MCP 服务器源码：工作量巨大，不可行
mcp-relay（类似项目）：功能较单一，不支持多传输模式
Cloudflare Workers 部署：需要额外学习成本

Supergateway 的优势在于极简部署 + 全面协议覆盖 + 开箱即用的 Claude/Cursor 集成。

局限与风险

无持久化 Web UI：纯 CLI 工具，调试依赖日志输出（--logLevel debug）
SSE → stdio 模式日志走 stderr：生产环境日志收集需注意
会话管理仅限 Streamable HTTP 有状态模式：SSE/WS 模式不支持会话
Cursor 的 Authorization Bug：需要绕道 --oauth2Bearer
ngrok 等内网穿透方案依赖外部服务：生产公网部署需自建反向代理

行业意义：MCP 生态的"黏合剂"

分析基于 GitHub 仓库 v3.4.3（2025年10月）