supercorp-ai/supergateway
Run MCP stdio servers over HTTP streamable, SSE and SSE over stdio. AI gateway.
Supergateway 的功能
Supergateway 是一款小巧的命令行工具，可让您通过不同的网络传输方式暴露或使用 MCP（模型上下文协议）服务器。MCP 服务器通常通过标准输入/输出（stdio）进行通信。Supergateway 可以：
- 包装本地基于 stdio 的 MCP 服务器，并使其可通过服务器发送事件（SSE）、WebSocket 或更新的 Streamable HTTP 协议访问。
- 连接到远程 MCP 服务器（已支持 SSE 或 Streamable HTTP），并将其作为本地 stdio 进程呈现。
- 组合多个 MCP 服务器（本地命令或远程 URL），通过单个 HTTP 端口提供访问，每个服务器位于自己的 URL 路径下。
- 添加可选功能，如 API 密钥认证、CORS、健康检查端点、自定义工具前缀和选择性工具暴露。
简而言之，它是一个传输网关，让开发者无需重写底层服务器，即可将基于 MCP 的 AI 工具集成到 Web 服务、调试设置或远程调试环境中。
适用人群
- AI 工具开发者：拥有仅支持 stdio 的 MCP 服务器，并希望将其暴露给浏览器或其他服务。
- 运维团队：需要在防火墙后运行 MCP 服务器，并通过 SSE/WS 暴露以进行远程调试。
- 产品团队：构建使用多个 MCP 工具（例如 Git 工具、文件系统工具）的 AI 增强型应用，并通过单个 HTTP 端点访问。
- 研究人员：尝试即将推出的 2026-07-28 MCP 协议版本，并需要快速测试有状态与无状态流。
如何开始
- 安装 – 最简单的方式是通过
npx（无需永久安装）或从 GitHub 发布页面下载预构建二进制文件。Homebrew 也提供了公式。 - 运行简单示例 – 通过 SSE 暴露本地文件系统 MCP 服务器：
客户端现在可以npx -y supergateway \ --stdio "npx -y @modelcontextprotocol/server-filesystem ./my-folder" \ --port 8000 --baseUrl http://localhost:8000 \ --ssePath /sse --messagePath /messageGET /sse接收事件，并通过POST /message发送请求。 - 尝试远程服务器 – 连接到现有的 SSE 端点并将其管道到终端：
npx -y supergateway --sse "https://example.com/mcp/sse" - 添加安全性 – 使用
--apiKey或--apiKeyFile要求每个客户端请求都携带 Bearer 令牌或标头。 - 组合服务器 – 创建
servers.json配置（与 Claude Desktop 使用的格式相同）并启动：
每个条目可通过npx -y supergateway --config servers.json/<name>/sse、/<name>/message等路径访问。
主要功能一览
| 功能 | 作用 |
|---|---|
| 传输转换 | stdio ↔ SSE、stdio ↔ WebSocket、stdio ↔ Streamable HTTP，以及远程 SSE/HTTP ↔ 上述任意一种。 |
| 多服务器支持 | 加载包含多个 MCP 服务器的 JSON-C 配置；每个服务器拥有自己的 URL 命名空间。 |
| 身份验证 | 要求 API 密钥（--apiKey、--apiKeyFile）或向上游服务器传递 OAuth2 Bearer 令牌/标头。 |
| 健康检查 | 自动提供 /healthz 端点，可验证网关本身或包装的 MCP 服务器。 |
| 工具控制 | 为工具名称添加前缀、仅暴露选定的工具，或完全隐藏其他工具。 |
| 日志记录 | 选择 info、debug 或 none；输出为纯文本或 JSON 以用于日志管道。 |
| CORS | 使用 --cors 启用跨域请求。 |
| 有状态 Streamable HTTP | 在 HTTP 请求之间保留会话状态（--stateful、--sessionTimeout）。 |
| 优雅关闭 | 当父进程结束（--exitWithProcess）或 stdin 关闭时退出。 |
| 独立二进制文件 | 发布版本包含适用于 macOS、Linux 和 Windows 的单个可执行文件——无需 Node.js。 |
限制与注意事项
- 仅限 MCP – Supergateway 仅适用于实现模型上下文协议的服务器；它不是通用的 HTTP 到 WebSocket 代理。
- 协议版本 – 网关默认使用协议版本
2024-11-05，但可通过--protocolVersion覆盖。客户端必须支持相同版本或协商回退。 - 每连接进程 – 在 stdio→SSE/WS 模式下，每个客户端都会生成自己的 MCP 进程，在高负载下可能增加资源使用。
- 安全性 – 除非您自行终止 TLS（例如通过反向代理），否则 API 密钥以明文发送。网关本身不提供 TLS。
- 无任务编排 – README 指出，组合服务器时“尚不支持”任务处理。
谁可能使用它
- AI 工具开发者，其 MCP 服务器仅支持 stdio，希望将其暴露给浏览器或其他服务。
- 运维团队，需要在防火墙后运行 MCP 服务器，并通过 SSE/WS 暴露以进行远程调试。
- 产品团队，构建使用多个 MCP 工具（例如 Git 工具、文件系统工具）的 AI 增强型应用，并通过单个 HTTP 端点访问。
- 研究人员，正在试验即将推出的 2026-07-28 MCP 协议版本，并需要一种快速测试有状态与无状态流的方法。
如何开始
- 安装 – 最简单的方式是通过
npx（无需永久安装）或从 GitHub 发布页面下载预构建二进制文件。Homebrew 也提供了公式。 - 运行简单示例 – 通过 SSE 暴露本地文件系统 MCP 服务器：
客户端现在可以npx -y supergateway \ --stdio "npx -y @modelcontextprotocol/server-filesystem ./my-folder" \ --port 8000 --baseUrl http://localhost:8000 \ --ssePath /sse --messagePath /messageGET /sse接收事件，并通过POST /message发送请求。 - 尝试远程服务器 – 连接到现有的 SSE 端点并将其传输到终端：
npx -y supergateway --sse "https://example.com/mcp/sse" - 添加安全性 – 使用
--apiKey或--apiKeyFile要求每个客户端请求都带有 bearer token 或 header。 - 组合服务器 – 创建
servers.json配置（与 Claude Desktop 使用的格式相同）并启动：
每个条目在npx -y supergateway --config servers.json/<name>/sse、/<name>/message等路径下可用。
主要功能一览
| 功能 | 作用 |
|---|---|
| 传输转换 | stdio ↔ SSE、stdio ↔ WebSocket、stdio ↔ Streamable HTTP，以及远程 SSE/HTTP ↔ 上述任意一种。 |
| 多服务器支持 | 加载包含多个 MCP 服务器的 JSON-C 配置；每个服务器拥有自己的 URL 命名空间。 |
| 身份验证 | 要求 API 密钥（--apiKey、--apiKeyFile）或向上游服务器传递 OAuth2 Bearer 令牌/标头。 |
| 健康检查 | 自动 /healthz 端点，可验证网关本身或包装的 MCP 服务器。 |
| 工具控制 | 为工具名称添加前缀、仅暴露选定的工具，或完全隐藏其他工具。 |
| 日志记录 | 选择 info、debug 或 none；输出为纯文本或 JSON 以用于日志管道。 |
| CORS | 使用 --cors 启用跨域请求。 |
| 有状态 Streamable HTTP | 在 HTTP 请求之间保留会话状态（--stateful、--sessionTimeout）。 |
| 优雅关闭 | 在父进程结束（--exitWithProcess）或 stdin 关闭时退出。 |
| 独立二进制文件 | 发布版本包含适用于 macOS、Linux 和 Windows 的单个可执行文件——无需 Node.js。 |
限制与注意事项
- 仅限 MCP – Supergateway 仅适用于实现模型上下文协议的服务器；它不是通用的 HTTP 到 WebSocket 代理。
- 协议版本 – 网关默认使用协议版本
2024-11-05，但可通过--protocolVersion覆盖。客户端必须支持相同版本或协商回退。 - 每连接进程 – 在 stdio→SSE/WS 模式下，每个客户端都会生成自己的 MCP 进程，在高负载下可能增加资源使用。
- 安全性 – 除非您自行终止 TLS（例如通过反向代理），否则 API 密钥以明文发送。网关本身不提供 TLS。
- 无任务编排 – README 指出，组合服务器时“尚不支持”任务处理。
快速参考速查表
# 基本 stdio → SSE
npx -y supergateway --stdio "my-mcp" --port 8000 --ssePath /sse --messagePath /msg
# 远程 SSE → stdio（本地调试）
npx -y supergateway --sse "https://host/mcp/sse"
# stdio → Streamable HTTP（无状态）
npx -y supergateway --stdio "my-mcp" --outputTransport streamableHttp --port 8000
# stdio → Streamable HTTP（有状态，60 秒超时）
npx -y supergateway --stdio "my-mcp" \
--outputTransport streamableHttp --stateful \
--sessionTimeout 60000 --port 8000
# 添加 API 密钥保护
npx -y supergateway ... --apiKey "SECRET"
# 从配置文件加载多个服务器
npx -y supergateway --config servers.json
下一步
- 阅读完整文档 – README 链接到健康检查、工具前缀和组合服务器的详细章节。
- 加入社区 – 该项目宣传了一个 Discord 服务器，用于提问和分享想法。
- 探索 MCP – 如果您是模型上下文协议的新手，请查看官方 MCP 规范和示例中引用的
@modelcontextprotocolnpm 包。 - 贡献 – 该仓库附带 CLI、配置解析器和二进制发布；围绕 TLS 终止、任务支持或额外传输方式的贡献将非常有价值。
相关
- 项目
- 项目
- 项目
- Dispatch
- 项目