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

Supergateway教程

news 2025/8/4 8:18:26

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.xdnf.cn/news/1236097.html

相关文章：

  • 使用DrissionPage实现xhs笔记自动翻页并爬取笔记视频、图片
  • Day22--回溯--77. 组合，216. 组合总和 III，17. 电话号码的字母组合
  • Kafka 是什么？
  • 《汇编语言：基于X86处理器》第11章 MS-Windows编程(3)
  • 【stm32】按键控制LED以及光敏传感器控制蜂鸣器
  • OSPF知识点整理
  • 实战《从0开始使用SwiftUI搭建记账软件》- 2、SwiftUI 知识点详解与使用场景
  • 6.1、Redis多级缓存原理和优化、Redis部分参数优化调整
  • 【超分辨率专题】PiSA-SR：单步Diff超分新突破，即快又好，还能在线调参
  • Linux 摄像头实时抓取：V4L2、FFmpeg 与 GStreamer 全面讲解
  • python工具方法51 视频数据的扩充（翻转、resize、crop、re_fps）
  • Transformer模型用于MT信号相关性预测与分析
  • 《深入浅出RabbitMQ：从零基础到面试通关》
  • 渗透作业4
  • wordpress登陆前登陆后显示不同的顶部菜单
  • 数据结构代码
  • 08.Redis 持久化
  • AOP动态代理
  • #C语言——刷题攻略：牛客编程入门训练（四）：运算
  • 大屏项目展示
  • 面向智能体的上下文工程：策略、实现与 LangGraph 实践
  • 09.Redis 常用命令
  • STM32-ESP8266通过MQTT与阿里云通讯
  • Coze 打通飞书多维表格，实现数据增删改查操作实战详解
  • Java线程安全类设计思路总结
  • kafka 是一个怎样的系统？是消息队列（MQ）还是一个分布式流处理平台？
  • RabbitMQ死信队列与消息幂等性实践指南
  • Rust：如何访问 *.ini 配置文件？
  • 关于车位引导及汽车乘梯解决方案的专业性、系统性、可落地性强的综合设计方案与技术实现说明，旨在为现代智慧停车楼提供高效、安全、智能的停车体验。
  • Noob靶场练习