Supergateway
supercorp-ai/supergateway
Execute servidores MCP stdio sobre SSE, WS e HTTP Streamable
Ver no GitHubServidor MCP que executa aplicações baseadas em stdio sobre SSE, WebSockets ou HTTP Streamable com um único comando. Permite expor servidores MCP locais remotamente ou conectar a clientes que suportam apenas stdio, facilitando integração, debugging e acesso remoto.
Instalação
npx convez-ai supercorp-ai/supergateway1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Expor servidores MCP locais remotamente via SSE ou WebSocket
- Integrar servidores MCP remotos em ambientes locais de CLI
- Debug e troubleshooting de servidores MCP distribuídos
- Criar gateways HTTP para servidores MCP legados ou stdio-only
Veredito

Ferramenta robusta e agnóstica para transpor barreiras de transporte entre servidores MCP. Ideal para cenários de integração complexa, infraestrutura distribuída e debugging remoto, com suporte completo a autenticação e customização de headers.
README
A tradução para o português deste README ainda está na fila.

Supergateway runs MCP stdio-based servers over SSE (Server-Sent Events) or WebSockets (WS) with one command. This is useful for remote access, debugging, or connecting to clients when your MCP server only supports stdio.
Supported by Supermachine (hosted MCPs), Superinterface, and Supercorp.
Installation & Usage
Run Supergateway via npx:
npx -y supergateway --stdio "uvx mcp-server-git"
--stdio "command": Command that runs an MCP server over stdio--sse "https://mcp-server-ab71a6b2-cd55-49d0-adba-562bc85956e3.supermachine.app": SSE URL to connect to (SSE→stdio mode)--streamableHttp "https://mcp-server.example.com/mcp": Streamable HTTP URL to connect to (StreamableHttp→stdio mode)--outputTransport stdio | sse | ws | streamableHttp: Output MCP transport (default:ssewith--stdio,stdiowith--sseor--streamableHttp)--port 8000: Port to listen on (stdio→SSE or stdio→WS mode, default:8000)--baseUrl "http://localhost:8000": Base URL for SSE or WS clients (stdio→SSE mode; optional)--ssePath "/sse": Path for SSE subscriptions (stdio→SSE mode, default:/sse)--messagePath "/message": Path for messages (stdio→SSE or stdio→WS mode, default:/message)--streamableHttpPath "/mcp": Path for Streamable HTTP (stdio→Streamable HTTP mode, default:/mcp)--stateful: Run stdio→Streamable HTTP in stateful mode--sessionTimeout 60000: Session timeout in milliseconds (stateful stdio→Streamable HTTP mode only)--header "x-user-id: 123": Add one or more headers (stdio→SSE, SSE→stdio, or Streamable HTTP→stdio mode; can be used multiple times)--oauth2Bearer "some-access-token": Adds anAuthorizationheader with the provided Bearer token--logLevel debug | info | none: Controls logging level (default:info). Usedebugfor more verbose logs,noneto suppress all logs.--cors: Enable CORS (stdio→SSE or stdio→WS mode). Use--corswith no values to allow all origins, or supply one or more allowed origins (e.g.--cors "http://example.com"or--cors "/example\\.com$/"for regex matching).--healthEndpoint /healthz: Register one or more endpoints (stdio→SSE or stdio→WS mode; can be used multiple times) that respond with"ok"
stdio → SSE
Expose an MCP stdio server as an SSE server:
npx -y supergateway \
--stdio "npx -y @modelcontextprotocol/server-filesystem ./my-folder" \
--port 8000 --baseUrl http://localhost:8000 \
--ssePath /sse --messagePath /message
- Subscribe to events:
GET http://localhost:8000/sse - Send messages:
POST http://localhost:8000/message
SSE → stdio
Connect to a remote SSE server and expose locally via stdio:
npx -y supergateway --sse "https://mcp-server-ab71a6b2-cd55-49d0-adba-562bc85956e3.supermachine.app"
Useful for integrating remote SSE MCP servers into local command-line environments.
You can also pass headers when sending requests. This is useful for authentication:
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"
Streamable HTTP → stdio
Connect to a remote Streamable HTTP server and expose locally via stdio:
npx -y supergateway --streamableHttp "https://mcp-server.example.com/mcp"
This mode is useful for connecting to MCP servers that use the newer Streamable HTTP transport protocol. Like SSE mode, you can also pass headers for authentication:
npx -y supergateway \
--streamableHttp "https://mcp-server.example.com/mcp" \
--oauth2Bearer "some-access-token" \
--header "X-My-Header: another-header-value"
stdio → Streamable HTTP
Expose an MCP stdio server as a Streamable HTTP server.
Stateless mode
npx -y supergateway \
--stdio "npx -y @modelcontextprotocol/server-filesystem ./my-folder" \
--outputTransport streamableHttp \
--port 8000
Stateful mode
npx -y supergateway \
--stdio "npx -y @modelcontextprotocol/server-filesystem ./my-folder" \
--outputTransport streamableHttp --stateful \
--sessionTimeout 60000 --port 8000
The Streamable HTTP endpoint defaults to http://localhost:8000/mcp (configurable via --streamableHttpPath).
stdio → WS
Expose an MCP stdio server as a WebSocket server:
npx -y supergateway \
--stdio "npx -y @modelcontextprotocol/server-filesystem ./my-folder" \
--port 8000 --outputTransport ws --messagePath /message
- WebSocket endpoint:
ws://localhost:8000/message
Example with MCP Inspector (stdio → SSE mode)
- Run Supergateway:
npx -y supergateway --port 8000 \
--stdio "npx -y @modelcontextprotocol/server-filesystem /Users/MyName/Desktop"
- Use MCP Inspector:
npx @modelcontextprotocol/inspector
You can now list tools, resources, or perform MCP actions via Supergateway.
Using with ngrok
Use ngrok to share your local MCP server publicly:
npx -y supergateway --port 8000 --stdio "npx -y @modelcontextprotocol/server-filesystem ."
# In another terminal:
ngrok http 8000
ngrok provides a public URL for remote access.
MCP server will be available at URL similar to: https://1234-567-890-12-456.ngrok-free.app/sse
Running with Docker
A Docker-based workflow avoids local Node.js setup. A ready-to-run Docker image is available here: supercorp/supergateway. Also on GHCR: ghcr.io/supercorp-ai/supergateway
Using the Official Image
docker run -it --rm -p 8000:8000 supercorp/supergateway \
--stdio "npx -y @modelcontextprotocol/server-filesystem /" \
--port 8000
Docker pulls the image automatically. The MCP server runs in the container’s root directory (/). You can mount host directories if needed.
Images with dependencies
Pull any of these pre-built Supergateway images for various dependencies you might need.
-
uvx Supergateway + uv/uvx, so you can call
uvxdirectly:docker run -it --rm -p 8000:8000 supercorp/supergateway:uvx \ --stdio "uvx mcp-server-fetch" -
deno Supergateway + Deno, ready to run Deno-based MCP servers:
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"
Building the Image Yourself
Use provided Dockerfile:
docker build -f docker/base.Dockerfile -t supergateway .
docker run -it --rm -p 8000:8000 supergateway --stdio "npx -y @modelcontextprotocol/server-filesystem ."
Using with Claude Desktop (SSE → stdio mode)
Claude Desktop can use Supergateway’s SSE→stdio mode.
NPX-based MCP Server Example
{
"mcpServers": {
"supermachineExampleNpx": {
"command": "npx",
"args": [
"-y",
"supergateway",
"--sse",
"https://mcp-server-ab71a6b2-cd55-49d0-adba-562bc85956e3.supermachine.app"
]
}
}
}
Docker-based MCP Server Example
{
"mcpServers": {
"supermachineExampleDocker": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"supercorp/supergateway",
"--sse",
"https://mcp-server-ab71a6b2-cd55-49d0-adba-562bc85956e3.supermachine.app"
]
}
}
}
Using with Cursor (SSE → stdio mode)
Cursor can also integrate with Supergateway in SSE→stdio mode. The configuration is similar to Claude Desktop.
NPX-based MCP Server Example for Cursor
{
"mcpServers": {
"cursorExampleNpx": {
"command": "npx",
"args": [
"-y",
"supergateway",
"--sse",
"https://mcp-server-ab71a6b2-cd55-49d0-adba-562bc85956e3.supermachine.app"
]
}
}
}
Docker-based MCP Server Example for Cursor
{
"mcpServers": {
"cursorExampleDocker": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"supercorp/supergateway",
"--sse",
"https://mcp-server-ab71a6b2-cd55-49d0-adba-562bc85956e3.supermachine.app"
]
}
}
}
Note: Although the setup supports sending headers via the --header flag, if you need to pass an Authorization header (which typically includes a space, e.g. "Bearer 123"), you must use the --oauth2Bearer flag due to a known Cursor bug with spaces in command-line arguments.
Why MCP?
Model Context Protocol standardizes AI tool interactions. Supergateway converts MCP stdio servers into SSE or WS services, simplifying integration and debugging with web-based or remote clients.
Advanced Configuration
Supergateway emphasizes modularity:
- Automatically manages JSON-RPC versioning.
- Retransmits package metadata where possible.
- stdio→SSE or stdio→WS mode logs via standard output; SSE→stdio mode logs via stderr.
Additional resources
- Superargs - provide arguments to MCP servers during runtime.
Contributors
- @longfin
- @griffinqiu
- @folkvir
- @wizizm
- @dtinth
- @rajivml
- @NicoBonaminio
- @sibbl
- @podarok
- @jmn8718
- @TraceIvan
- @zhoufei0622
- @ezyang
- @aleksadvaisly
- @wuzhuoquan
- @mantrakp04
- @mheubi
- @mjmendo
- @CyanMystery
- @earonesty
- @StefanBurscher
- @tarasyarema
- @pcnfernando
- @Areo-Joe
- @Joffref
- @michaeljguarino
Contributing
Issues and PRs welcome. Please open one if you encounter problems or have feature suggestions.
Tests
Supergateway is tested with the Node Test Runner.
To run the suite locally you need Node 24+. Using nvm you can install and activate it with:
nvm install 24
nvm use 24
npm install
npm run build
npm test
The tests/helpers/mock-mcp-server.js script provides a local MCP server so all
tests run without network access.