当前位置： 首页 > news >正文

Supergateway教程

news 2025/8/4 7:52:19

Supergateway 是一款专为 MCP（Model Context Protocol）服务器设计的远程调试与集成工具，通过
SSE（Server-Sent Events）或 WebSocket（WS）协议实现基于 stdio 的服务器与客户端的高效通信。

Supergateway 只需一个命令即可通过 SSE（服务器发送事件） 或 WebSockets（WS） 运行基于 MCP stdio 的服务器 。当您的 MCP 服务器仅支持 stdio 时，此功能对于远程访问、调试或连接客户端非常有用。

由 Supermachine (托管 MCP)、 Superinterface 和 Supercorp 支持。

前置条件

  1. 本次使用的是CentOS Stream 9
  2. 安装node 24
## 安装nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
## 更新环境变量
source ~/.bashrc
## nvm安装node24
nvm install 24
## nvm使用node24
nvm use 24

Supergateway安装与使用

通过 npx 运行 Supergateway：

npx -y supergateway --stdio "uvx mcp-server-git"
  • --stdio "command" ：通过 stdio 运行 MCP 服务器的命令
  • --sse "https://mcp-server-ab71a6b2-cd55-49d0-adba-562bc85956e3.supermachine.app" ：要连接的 SSE URL（SSE→stdio 模式）
  • --streamableHttp "https://mcp-server.example.com/mcp" ：要连接的可流式 HTTP URL（StreamableHttp→stdio 模式）
  • --outputTransport stdio | sse | ws | streamableHttp ：输出 MCP 传输（默认值： sse 带有 --stdio ， stdio 带有 --sse 或 --streamableHttp ）
  • --port 8000 ：监听端口（stdio→SSE 或 stdio→WS 模式，默认值： 8000 ）
  • --baseUrl "http://localhost:8000" ：SSE 或 WS 客户端的基本 URL（stdio→SSE 模式；可选）
  • --ssePath "/sse" ：SSE 订阅的路径（stdio→SSE 模式，默认值： /sse ）
  • --messagePath "/message" ：消息路径（stdio→SSE 或 stdio→WS 模式，默认值： /message ）
  • --streamableHttpPath "/mcp" ：Streamable HTTP 的路径（stdio→Streamable HTTP 模式，默认值： /mcp ）
  • --stateful ：以状态模式运行 stdio→Streamable HTTP
  • --sessionTimeout 60000 ：会话超时（以毫秒为单位）（仅限有状态 stdio→Streamable HTTP 模式）
  • --header "x-user-id: 123" ：添加一个或多个标头（stdio→SSE、SSE→stdio 或 Streamable HTTP→stdio 模式；可多次使用）
  • --oauth2Bearer "some-access-token" ：使用提供的 Bearer 令牌添加 Authorization 标头
  • --logLevel debug | info | none ：控制日志记录级别（默认值： info ）。使用 debug 可显示更详细的日志，使用 none 可隐藏所有日志。
  • --cors ：启用 CORS（stdio→SSE 或 stdio→WS 模式）。使用不带任何值的 --cors 参数表示允许所有来源，或提供一个或多个允许的来源（例如， --cors "http://example.com" 或 --cors "/example\\.com$/" 进行正则匹配）。
  • --healthEndpoint /healthz ：注册一个或多个以 "ok" 响应的端点（stdio→SSE 或 stdio→WS 模式；可多次使用）

标准输入输出 → SSE

将 MCP stdio 服务器公开为 SSE 服务器：

npx -y supergateway \--stdio "npx -y @modelcontextprotocol/server-filesystem ./my-folder" \--port 8000 --baseUrl http://localhost:8000 \--ssePath /sse --messagePath /message
  • 订阅事件 ： GET http://localhost:8000/sse
  • 发送消息 ： POST http://localhost:8000/message

出现如下，说明启动成功

[root@VM-12-16-centos my-folder]# npx -y supergateway --stdio "npx -y @modelcontextprotocol/server-filesystem /root/my-folder" --port 8000 --baseUrl http://localhost:8000 --ssePath /sse --messagePath /message
[supergateway] Starting...
[supergateway] Supergateway is supported by Supermachine (hosted MCPs) - https://supermachine.ai
[supergateway]   - outputTransport: sse
[supergateway]   - Headers: (none)
[supergateway]   - port: 8000
[supergateway]   - stdio: npx -y @modelcontextprotocol/server-filesystem /root/my-folder
[supergateway]   - baseUrl: http://localhost:8000
[supergateway]   - ssePath: /sse
[supergateway]   - messagePath: /message
[supergateway]   - CORS: disabled
[supergateway]   - Health endpoints: (none)
[supergateway] Listening on port 8000
[supergateway] SSE endpoint: http://localhost:8000/sse
[supergateway] POST messages: http://localhost:8000/message
[supergateway] Child stderr: Secure MCP Filesystem Server running on stdio

如果是远程腾讯云服务器，需要先开放防火墙，

sudo firewall-cmd --permanent --add-port=8000/tcp
sudo firewall-cmd --reload

外层也要添加
在这里插入图片描述

后启动（需要添加host 0.0.0.0）：

npx -y supergateway \--stdio "npx -y @modelcontextprotocol/server-filesystem /root/my-folder" \--port 8000 \--host 0.0.0.0 \--baseUrl http://腾讯云服务器公网ip:8000 \--ssePath /sse \--messagePath /message

返回如下：

[root@VM-12-16-centos my-folder]# npx -y supergateway \--stdio "npx -y @modelcontextprotocol/server-filesystem /root/my-folder" \--port 8000 \--host 0.0.0.0 \--baseUrl http://腾讯云服务器公网ip:8000 \--ssePath /sse \--messagePath /message
[supergateway] Starting...
[supergateway] Supergateway is supported by Supermachine (hosted MCPs) - https://supermachine.ai
[supergateway]   - outputTransport: sse
[supergateway]   - Headers: (none)
[supergateway]   - port: 8000
[supergateway]   - stdio: npx -y @modelcontextprotocol/server-filesystem /root/my-folder
[supergateway]   - baseUrl: http://腾讯云服务器公网ip:8000
[supergateway]   - ssePath: /sse
[supergateway]   - messagePath: /message
[supergateway]   - CORS: disabled
[supergateway]   - Health endpoints: (none)
[supergateway] Listening on port 8000
[supergateway] SSE endpoint: http://localhost:8000/sse
[supergateway] POST messages: http://localhost:8000/message
[supergateway] Child stderr: Secure MCP Filesystem Server running on stdio

使用本地windows远程连接测试，如下，服务没问题

C:\Users\longz>curl http://腾讯云服务器公网ip:8000/sse
event: endpoint
data: /message?sessionId=e3819502-97bc-4c8b-a15c-f31179c2fe00

我们使用mcp客户端trae连接
在这里插入图片描述

{"mcpServers": {"remote-filesystem": {"url": "http://腾讯云公网ip:8000/sse","headers": {}}}
}

如下显示成功
在这里插入图片描述

补充备注： 上述方法是比较通用，不限腾讯云服务器。其余均可。 腾讯云服务器本身也提供了封装mcp服务的模板，提供支持一键云端部署 MCP
Server

在这里插入图片描述

SSE → stdio

连接到远程 SSE 服务器并通过 stdio 在本地公开：

npx -y supergateway --sse "https://mcp-server-ab71a6b2-cd55-49d0-adba-562bc85956e3.supermachine.app"

适用于将远程 SSE MCP 服务器集成到本地命令行环境中。

发送请求时，你还可以传递 headers。这对于身份验证很有用：

npx -y supergateway \--sse "https://mcp-server-ab71a6b2-cd55-49d0-adba-562bc85956e3.supermachine.app" \--oauth2Bearer "some-access-token" \--header "X-My-Header: another-header-value"

可流式传输的 HTTP → stdio

连接到远程 Streamable HTTP 服务器并通过 stdio 在本地公开：

npx -y supergateway --streamableHttp "https://mcp-server.example.com/mcp"

此模式适用于连接到使用较新的 Streamable HTTP 传输协议的 MCP 服务器。与 SSE 模式类似，您也可以传递以下标头进行身份验证：

npx -y supergateway \--streamableHttp "https://mcp-server.example.com/mcp" \--oauth2Bearer "some-access-token" \--header "X-My-Header: another-header-value"

stdio → 可流式传输的 HTTP

将 MCP stdio 服务器公开为可流式传输的 HTTP 服务器。

无状态模式

npx -y supergateway \--stdio "npx -y @modelcontextprotocol/server-filesystem ./my-folder" \--outputTransport streamableHttp \--port 8000

状态模式

npx -y supergateway \--stdio "npx -y @modelcontextprotocol/server-filesystem ./my-folder" \--outputTransport streamableHttp --stateful \--sessionTimeout 60000 --port 8000

Streamable HTTP 端点默认为 http://localhost:8000/mcp (可通过 --streamableHttpPath 配置)。

标准输入输出 → WS

将 MCP stdio 服务器公开为 WebSocket 服务器：

npx -y supergateway \--stdio "npx -y @modelcontextprotocol/server-filesystem ./my-folder" \--port 8000 --outputTransport ws --messagePath /message
  • WebSocket 端点 ： ws://localhost:8000/message

MCP Inspector 示例（stdio → SSE 模式）

  1. 运行超级网关 ：
npx -y supergateway --port 8000 \--stdio "npx -y @modelcontextprotocol/server-filesystem /Users/MyName/Desktop"
  1. 使用 MCP 检查器 ：
npx @modelcontextprotocol/inspector

您现在可以通过 Supergateway 列出工具、资源或执行 MCP 操作。

与 ngrok 一起使用

使用 ngrok 公开分享您的本地 MCP 服务器：

npx -y supergateway --port 8000 --stdio "npx -y @modelcontextprotocol/server-filesystem ."# In another terminal:
ngrok http 8000

ngrok 提供了一个用于远程访问的公共 URL。

MCP 服务器的 URL 类似于： https://1234-567-890-12-456.ngrok-free.app/sse

使用 Docker 运行

基于 Docker 的工作流程避免了本地 Node.js 的设置。可在此处获取随时可用的 Docker 镜像： supercorp/supergateway。GHCR 上也有： ghcr.io/supercorp-ai/supergateway

使用官方镜像

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

Docker 会自动拉取镜像。MCP 服务器在容器的根目录 ( / ) 中运行。您可以根据需要挂载主机目录。

具有依赖关系的图像

提取这些预先构建的 Supergateway 图像以满足您可能需要的各种依赖项。

  • 紫外线 超级网关+uv/uvx，这样你就可以直接调用 uvx ：

    docker run -it --rm -p 8000:8000 supercorp/supergateway:uvx \--stdio "uvx mcp-server-fetch"

  • 德诺 Supergateway + Deno，准备运行基于 Deno 的 MCP 服务器：

    docker run -it --rm -p 8000:8000 supercorp/supergateway:deno \--stdio "deno run -A jsr:@omedia/mcp-server-drupal --drupal-url https://your-drupal-server.com"

自己构建图像

使用提供的 Dockerfile：

docker build -f docker/base.Dockerfile -t supergateway .docker run -it --rm -p 8000:8000 supergateway --stdio "npx -y @modelcontextprotocol/server-filesystem ."

与 Claude Desktop 一起使用（SSE → stdio 模式）

Claude Desktop 可以使用 Supergateway 的 SSE→stdio 模式。

基于 NPX 的 MCP 服务器示例

{"mcpServers": {"supermachineExampleNpx": {"command": "npx","args": ["-y","supergateway","--sse","https://mcp-server-ab71a6b2-cd55-49d0-adba-562bc85956e3.supermachine.app"]}}
}

基于 Docker 的 MCP 服务器示例

{"mcpServers": {"supermachineExampleDocker": {"command": "docker","args": ["run","-i","--rm","supercorp/supergateway","--sse","https://mcp-server-ab71a6b2-cd55-49d0-adba-562bc85956e3.supermachine.app"]}}
}

与 Cursor 一起使用（SSE → stdio 模式）

Cursor 还可以通过 SSE→stdio 模式与 Supergateway 集成。配置方式与 Claude Desktop 类似。

基于 NPX 的 MCP 服务器游标示例

{"mcpServers": {"cursorExampleNpx": {"command": "npx","args": ["-y","supergateway","--sse","https://mcp-server-ab71a6b2-cd55-49d0-adba-562bc85956e3.supermachine.app"]}}
}

基于 Docker 的 Cursor MCP 服务器示例

{"mcpServers": {"cursorExampleDocker": {"command": "docker","args": ["run","-i","--rm","supercorp/supergateway","--sse","https://mcp-server-ab71a6b2-cd55-49d0-adba-562bc85956e3.supermachine.app"]}}
}

注意： 尽管设置支持通过 --header 标志发送标头，但如果您需要传递授权标头（通常包含空格，例如 "Bearer 123" ），则必须使用 --oauth2Bearer 标志，因为已知的 Cursor 错误导致命令行参数中有空格。

为什么选择 MCP？

模型上下文协议 (MCP) 标准化了 AI 工具的交互。Supergateway 将 MCP 标准输入输出 (stdio) 服务器转换为 SSE 或 WS 服务，从而简化了与基于 Web 或远程客户端的集成和调试。

高级配置

超级网关强调模块化：

  • 自动管理 JSON-RPC 版本。
  • 尽可能重新传输包元数据。
  • stdio→SSE 或 stdio→WS 模式通过标准输出记录；SSE→stdio 模式通过 stderr 记录。

测试

Supergateway 使用 Node Test Runner 进行测试。

tests/helpers/mock-mcp-server.js 脚本提供了本地 MCP 服务器，因此所有测试都无需网络访问即可运行。

SE)

http://www.lryc.cn/news/608795.html

相关文章：

  • Baumer工业相机堡盟工业相机如何通过YoloV8深度学习模型实现各类垃圾的分类检测识别（C#代码UI界面版）
  • 玩转 Playwright 有头与无头模式：消除差异，提升爬虫稳定性
  • LLM - 智能体工作流设计模式
  • 小红书开源dots.ocr：单一视觉语言模型中的多语言文档布局解析
  • 【设计模式】5.代理模式
  • [LeetCode优选算法专题一双指针——有效三角形的个数]
  • Python 程序设计讲义（60）：Python 的函数——递归函数
  • 从“配置地狱”到“云端乐园”——Nacos 如何成为分布式微服务配置中心的“定海神针”
  • 【MySQL】MySQL中锁有哪些？
  • ethtool,lspci,iperf工具常用命令总结
  • 26李林880高数第一章 函数、极限、连续
  • Shell脚本-变量的定义规则
  • 西门子PLC基础指令4：输出指令、立即输出指令
  • JavaScript 性能优化实战指南：从运行时到用户体验的全面提升​
  • adb 与pad 交互方法
  • MyBatis动态SQL精要：从＜if＞到＜foreach＞的灵活拼接之道
  • Go语言声明变量
  • 怎么修改论文格式呢？提供一份论文格式模板
  • 【Bluedroid】btif_av_handle_event 流程源码解析
  • 面向智能体的上下文工程：策略、实现与 LangGraph 实践
  • LangChain4J入门：接入大模型
  • 系统学习算法：专题十六 字符串
  • 第三章-提示词-高级：开启智能交互新境界（13/36）
  • 日常--详细介绍qt Designer常用快捷键（详细图文）
  • 【QT】概述
  • 高质量数据集｜建设三大难点
  • 01.MySQL 安装
  • 服务器中切换盘的操作指南
  • Android 之 MVVM架构
  • 使用 Docker 部署 Golang 程序