Supergateway教程

Supergateway 是一款專為 MCP（Model Context Protocol）服務器設計的遠程調試與集成工具，通過
SSE（Server-Sent Events）或 WebSocket（WS）協議實現基于 stdio 的服務器與客戶端的高效通信。

Supergateway 只需一個命令即可通過 SSE（服務器發送事件） 或 WebSockets（WS） 運行基于 MCP stdio 的服務器 。當您的 MCP 服務器僅支持 stdio 時，此功能對于遠程訪問、調試或連接客戶端非常有用。

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

前置條件

本次使用的是CentOS Stream 9
安裝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 模式）

運行超級網關 ：

npx -y supergateway --port 8000 \--stdio "npx -y @modelcontextprotocol/server-filesystem /Users/MyName/Desktop"

使用 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 錯誤導致命令行參數中有空格。