supercorp-ai/supergateway

What Supergateway does

Supergateway is a tiny command‑line tool that lets you expose or consume MCP (Model‑Context‑Protocol) servers over different network transports. An MCP server normally talks over standard input/output (stdio). Supergateway can:

Wrap a local stdio‑based MCP server and make it reachable via Server‑Sent Events (SSE), WebSockets, or the newer Streamable HTTP protocol.
Connect to a remote MCP server that already speaks SSE or Streamable HTTP, and present it locally as a stdio process.
Combine several MCP servers (local commands or remote URLs) behind a single HTTP port, each under its own URL path.
Add optional features such as API‑key authentication, CORS, health‑check endpoints, custom tool prefixes, and selective tool exposure.

In short, it’s a transport‑gateway that lets developers integrate MCP‑based AI tools into web services, debugging setups, or remote debugging environments without rewriting the underlying server.

Who might use it

AI‑tool developers who have an MCP server that only works over stdio and want to expose it to browsers or other services.
Ops teams that need to run an MCP server behind a firewall and expose it via SSE/WS for remote debugging.
Product teams building AI‑augmented applications that consume multiple MCP tools (e.g., a Git tool, a file‑system tool) through a single HTTP endpoint.
Researchers experimenting with the upcoming 2026‑07‑28 MCP protocol version and needing a quick way to test stateful vs. stateless streams.

How to get started

Install – the easiest way is via npx (no permanent install needed) or by downloading a pre‑built binary from the GitHub releases page. Homebrew also provides a formula.

Run a simple example – expose a local filesystem MCP server over SSE:

npx -y supergateway \
    --stdio "npx -y @modelcontextprotocol/server-filesystem ./my-folder" \
    --port 8000 --baseUrl http://localhost:8000 \
    --ssePath /sse --messagePath /message

Clients can now GET /sse to receive events and POST /message to send requests.

Try a remote server – connect to an existing SSE endpoint and pipe it to your terminal:
```
npx -y supergateway --sse "https://example.com/mcp/sse"
```
Add security – use --apiKey or --apiKeyFile to require a bearer token or header on every client request.
Combine servers – create a servers.json config (the same format Claude Desktop uses) and launch:
```
npx -y supergateway --config servers.json
```
Each entry becomes available under /<name>/sse, /<name>/message, etc.

Key features at a glance

Feature	What it does
Transport conversion	stdio ↔ SSE, stdio ↔ WebSocket, stdio ↔ Streamable HTTP, and remote SSE/HTTP ↔ any of the above.
Multiple server support	Load a JSON‑C config with many MCP servers; each gets its own URL namespace.
Authentication	Require API keys (`--apiKey`, `--apiKeyFile`) or pass OAuth2 Bearer tokens/headers to upstream servers.
Health checks	Automatic `/healthz` endpoints that can verify the gateway itself or the wrapped MCP server.
Tool control	Prefix tool names, expose only selected tools, or hide others entirely.
Logging	Choose `info`, `debug`, or `none`; output as plain text or JSON for log pipelines.
CORS	Enable cross‑origin requests with `--cors`.
Stateful Streamable HTTP	Preserve session state across HTTP requests (`--stateful`, `--sessionTimeout`).
Graceful shutdown	Exit when a parent process ends (`--exitWithProcess`) or when stdin closes.
Standalone binaries	Releases include a single executable for macOS, Linux, and Windows – no Node.js required.

Limitations & things to watch out for

MCP‑specific – Supergateway only works with servers that implement the Model‑Context‑Protocol; it isn’t a generic HTTP‑to‑WebSocket proxy.
Protocol versioning – The gateway defaults to protocol version 2024‑11‑05 but can be overridden with --protocolVersion. Clients must support the same version or negotiate a fallback.
Per‑connection processes – In stdio→SSE/WS modes each client gets its own spawned MCP process, which can increase resource usage under heavy load.
Security – API keys are sent in clear text unless you terminate TLS yourself (e.g., behind a reverse proxy). The gateway does not provide TLS itself.
No task orchestration – The README notes that task handling is “not yet” supported when combining servers.

Quick reference cheat‑sheet

# Basic stdio → SSE
npx -y supergateway --stdio "my-mcp" --port 8000 --ssePath /sse --messagePath /msg

# Remote SSE → stdio (debug locally)
npx -y supergateway --sse "https://host/mcp/sse"

# stdio → Streamable HTTP (stateless)
npx -y supergateway --stdio "my-mcp" --outputTransport streamableHttp --port 8000

# stdio → Streamable HTTP (stateful, 60 s timeout)
npx -y supergateway --stdio "my-mcp" \
    --outputTransport streamableHttp --stateful \
    --sessionTimeout 60000 --port 8000

# Add API key protection
npx -y supergateway ... --apiKey "SECRET"

# Load many servers from a config file
npx -y supergateway --config servers.json

Where to go next

Read the full docs – the README links to sections on health checks, tool prefixes, and combined servers for deeper details.
Join the community – the project advertises a Discord server for questions and ideas.
Explore MCP – if you’re new to the Model‑Context‑Protocol, check the official MCP spec and the @modelcontextprotocol npm packages referenced in the examples.
Contribute – the repo ships with a CLI, config parser, and binary releases; contributions around TLS termination, task support, or additional transports would be valuable.