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. Questions, ideas or just want to chat? Join the community on . Supported by: - — Coverage for coding agents and software factories - -
Tools
Tools
No tool list yet. Remote servers get one after the first health check.
Copy the http config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.
Does Supergateway need an API key?
No required environment variable is listed on this record.
What transport does Supergateway use?
Supergateway is reached over HTTP.
When was Supergateway last checked?
Last checked 2026-11-11. 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. Questions, ideas or just want to chat? Join the community on . Supported by: - — Coverage for coding agents and software factories - -
From the publisher
Documentation
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.
Questions, ideas or just want to chat? Join the community on Discord.
Supported by:
Supercov — Coverage for coding agents and software factories 🌙
--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)
Key features
01. Run MCP stdio servers over HTTP streamable, SSE and SSE over stdio
02. Supergateway runs MCP stdio-based servers over SSE (Server-Sent Events) or WebSockets (WS) with one command
03. This is useful for remote access, debugging, or connecting to clients when your MCP server only supports stdio
04. Questions, ideas or just want to chat? Join the community on
05. Supported by: - — Coverage for coding agents and software factories - -
--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: sse with --stdio, stdio with --sse or --streamableHttp). A remote server given with --sse or --streamableHttp can be served over sse, ws or streamableHttp too; see Remote server → SSE, WS or Streamable HTTP
--port 8000: Port to listen on (stdio→SSE, stdio→WS or stdio→Streamable HTTP mode, default: 8000)
--host 127.0.0.1: Address to listen on, e.g. 127.0.0.1 or ::1 ([::1] also works) (stdio→SSE, stdio→WS or stdio→Streamable HTTP mode, default: every interface). --baseUrl does not control binding: only --host limits which addresses accept connections. Refused in SSE→stdio and Streamable HTTP→stdio mode, which listen on nothing
--baseUrl "http://localhost:8000": Base URL for SSE 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)
--protocolVersion "2025-06-18": Protocol version the gateway uses when it initializes the server itself and the client's request doesn't name one (stateless stdio→Streamable HTTP mode, default: 2024-11-05)
--header "x-user-id: 123": Add one or more headers (stdio→SSE, stdio→Streamable HTTP, SSE→stdio, or Streamable HTTP→stdio mode; can be used multiple times). With a local server they go on the gateway's responses; with a remote one (--sse, --streamableHttp) they are sent to the remote server
--oauth2Bearer "some-access-token": Adds an Authorization header with the provided Bearer token
--logLevel debug | info | none: Controls logging level (default: info). Use debug for more verbose logs, none to suppress all logs.
--logFormat text | json: Log line format (default: text). json writes one JSON object per line with time, level, msg and, when a log call carries values, data, for ELK and similar log pipelines. Logs go to the same streams as text, so stdio output still carries only MCP messages.
--cors: Enable CORS (stdio→SSE or stdio→WS mode). Use --cors with 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 (every mode but stdio output; can be used multiple times) that respond with "ok"
--healthCheck gateway | server: What the health endpoints check (default: gateway). gateway answers "ok" while the gateway is up. server also checks the MCP server: it starts one (or, for --sse/--streamableHttp, opens a session with the remote server), initializes and pings it, and stops it. It answers "ok" if the server responded within 10 seconds, and 503 with the reason otherwise (e.g. unhealthy: the server exited (code=1, signal=null)). The answer is reused for 10 seconds, so polling every second starts at most one server per 10 seconds. The startup log says when health turns bad and when it recovers
--toolPrefix "github_": Put this before every tool name the server lists, so search becomes github_search (all modes). Clients call the tool by that name, and the server still gets its own. It is used as given, so include a separator. Tool names may be letters, digits, _, - and ., at most 128 characters; the gateway warns about a prefix or name outside that
--tools search --tools get_issue: Expose only these tools, by the server's own names (all modes). The others are left out of tools/list, and a call to one is refused with -32602 Unknown tool, as a server refuses a tool it doesn't have, without reaching the server. A bare --tools exposes none
--apiKey "some-key": Require clients to present this key, as Authorization: Bearer <key> or X-API-Key: <key> (stdio→SSE, stdio→WS or stdio→Streamable HTTP mode; can be used multiple times). Also SUPERGATEWAY_API_KEY=some-key. See Requiring an API key
--apiKeyFile /run/secrets/keys: Accept the keys in this file, one per line (blank lines are skipped). Also SUPERGATEWAY_API_KEY_FILE=/run/secrets/keys
--exitWithProcess <pid>: Shut down, stopping the MCP server, when process <pid> exits (all modes). Pass the launcher's PID (e.g. $$); it need not be the direct parent, so it works through npx. Checked about once a second. A launcher that spawns Supergateway with a stdin pipe doesn't need this: since 4.0 Supergateway exits when its stdin closes.
--checkConfig: With --config, check the file, list each server's path and output, and exit
--printConfig: Print the resolved config and exit. Keys, bearer tokens, every env value, the query of every URL and headers with sensitive names are replaced; command lines (args, stdio) are printed as written, so read it over before sharing it. Without --config it prints the file equivalent to the command line given
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:
Expose an MCP stdio server as a Streamable HTTP server.
Supports legacy MCP and 2026-07-28 when the client and stdio server support a common protocol version. Clients that support automatic negotiation can fall back to legacy when the server requires it.
--stateful preserves legacy sessions. MCP 2026-07-28 uses independent requests and does not create a transport session.
Interactive MCP 2026-07-28 operations can continue across requests. Continuations and explicit retries are available for up to five minutes of inactivity, with at most 64 saved continuation states. Older states may expire sooner when this limit is reached.
Each client session gets its own session with the remote server, ended when the client's ends, and at shutdown.
--header and --oauth2Bearer go to the remote server. The client's own Authorization and API key never do.
Requests from the remote server to the client (sampling, roots, elicitation) are passed through.
A remote server that is down, refuses the client or goes away fails that session only.
The 2026-07-28 protocol's stateless requests are passed on to a remote Streamable HTTP server that speaks that version. The gateway asks it once a minute (server/discover). One that doesn't, and any remote SSE server, is served as before: its clients are told the version isn't supported, and those that negotiate fall back to an earlier one.
Requiring an API key
By default anyone who can reach the port can use the server. With --apiKey, every request to stdio→SSE, stdio→WS or stdio→Streamable HTTP must carry a key:
A request without a valid key gets 401 Unauthorized. The --healthEndpoint paths and, with --cors, browser preflight requests stay open.
Keys from --apiKey, --apiKeyFile, SUPERGATEWAY_API_KEY and SUPERGATEWAY_API_KEY_FILE are all accepted together, so a key can be rotated by adding the new one before removing the old.
An empty key, an unreadable key file or one with no keys stops the gateway at startup rather than running it without authentication.
Keys are never logged. Use HTTPS (e.g. behind a reverse proxy) so they are not sent in clear text.
To send a key to a remote server from SSE→stdio or Streamable HTTP→stdio, use --header or --oauth2Bearer; --apiKey is refused there.
Several servers from a config file
--config reads the mcpServers file that Claude Desktop and other MCP clients use, so a client's file works as-is. Each server is served at /<name> on one port:
git is served over SSE at http://localhost:8000/git/sse and /git/message; files over Streamable HTTP at http://localhost:8000/files/mcp.
A server is command + args (run without a shell, as clients run them), stdio (a shell command line, as --stdio), or url + type (sse or http). env and cwd set its environment and directory.
Any option from the list above can be set on a server, by its flag name (outputTransport, stateful, cors, headers, apiKey, healthEndpoint, toolPrefix, tools, ...). Set at the top level, it is the default for every server. Defaults are the command line's: a local server is served over SSE, a url one on stdio.
path serves a server somewhere other than /<name>. A name that can't be part of a URL needs one. The gateway refuses to start if a server's URL would be answered by another server or by the gateway's own healthEndpoint.
port, host, logLevel, logFormat, exitWithProcess and the top-level healthEndpoint are the gateway's own. A top-level healthEndpoint answers for the whole gateway; one on a server is under that server's path. With "healthCheck": "server", a server's own health endpoints check that server; the gateway's stay "ok" while the gateway is up, so one failing server doesn't fail the whole gateway.
apiKey on a server locks that server only, and replaces a top-level apiKey. An empty list is refused; to leave one server without a key, set apiKey on the servers that need one instead of at the top level. Keys from --apiKey, --apiKeyFile or SUPERGATEWAY_API_KEY lock every server.
"disabled": true skips a server. Keys only clients use (autoApprove, timeout, disabledTools, ...) are warned about and ignored. Any other unknown key is an error that suggests the closest known one.
${VAR}, ${VAR:-default} and ${env:VAR} are replaced from the environment in every value except a stdio command line, which the shell expands itself. A variable that isn't set is an error. $$ is a literal $.
Flags beside --config may be the gateway's own (--port, --host, --logLevel, --logFormat, --exitWithProcess, --healthEndpoint, --apiKey, --apiKeyFile). They override the file, and the startup log says so. A server flag such as --stateful is refused, because it would be unclear which server it means.
With more than one server, each log line about a server starts with its name ([git]), and JSON logs give it a server field.
On Windows, "command": "npx" works as it does in other clients: a command that is a script, such as npx.cmd, runs through cmd.exe, and each argument still reaches the server as written. stdio runs through the shell.
Comments and trailing commas are allowed (JSONC). Run --checkConfig after editing.
A url server is served like a local one when it has an output other than stdio (see Remote server → SSE, WS or Streamable HTTP): "outputTransport": "streamableHttp", for example.
One url server may use stdio output beside servers on the port. This is for a client that launches Supergateway with a config file, such as Claude Desktop: it talks to that server over stdin and stdout, and other clients reach the rest over HTTP. All logs then go to stderr. The process belongs to the client that started it. When stdin closes, a signal arrives, or the stdio server stops (its remote server refused the first connection, for example), every server stops, and the exit code is the stdio server's.
Combining servers on one URL
An entry with its own mcpServers serves them as one MCP server, at the entry's URL:
A client of http://localhost:8000/dev/mcp sees the tools, prompts and resources of all three.
Names are not changed. A request goes to the server that has the tool, prompt or resource it names. When two servers offer the same name, the first one listed wins and the other's is hidden; the log says so once. Set toolPrefix on a server to keep both, and tools to choose which of a server's tools are shown. Many tools behind one URL make a model's choice harder, so combine what belongs together.
Each session has its own servers, started when the client initializes. A server that can't start is left out, with a line in the log; the session fails only if none starts. A server that stops later fails the calls it had, the client is told the lists changed, and the rest go on.
Requests from a server to the client (sampling, roots, elicitation) work as they do for one server, on outputs that carry them (SSE, WebSocket, stateful Streamable HTTP).
The protocol version is the lowest any of the servers answers; the capabilities are everything any of them has; their instructions are joined, each under its server's name.
Lists come as one page, every server's in the order listed.
Settings for the URL (outputTransport, apiKey, cors, healthEndpoint, ...) go on the entry. A combined server has command/args/env/cwd, stdio, or url/type/headers/oauth2Bearer, and toolPrefix/tools. Combining goes one level deep.
On stdio ("outputTransport": "stdio"), a combined entry is what a desktop client launches to reach several servers through one entry of its own config. It can run beside servers on the port, as a single remote server can.
2026-07-28 is answered when every combined server speaks it (the gateway asks them once a minute). Each request then starts only the server it is for; server/discover and the lists go to every server. If one server doesn't speak it, the entry answers the earlier versions, and clients that negotiate fall back.
Not yet: tasks. Combined servers share one model context, so combine only servers you trust with each other's results.
Without Node: standalone executables
Each release also ships Supergateway as a single executable with Node built in, so it runs where Node is not installed. It takes the same flags.
Homebrew (macOS and Linux):
brew install supercorp-ai/tap/supergateway
macOS (Apple Silicon) and Linux: download and unpack. Use linux-x64, linux-arm64, linux-musl-x64 or linux-musl-arm64 in place of darwin-arm64 as needed.
curl -fsSL https://github.com/supercorp-ai/supergateway/releases/latest/download/supergateway-darwin-arm64.tar.gz | tar -xz
The MCP server you wrap still needs its own runtime: --stdio "npx -y ..." needs Node, --stdio "uvx ..." needs uv.
Linux needs glibc 2.28 or later. On Alpine use the linux-musl build and run apk add libstdc++ first.
Intel Macs have no standalone build; brew install gives them the npm package on Homebrew's Node instead.
The executables are not code-signed by a paid certificate. Downloaded from a browser, macOS Gatekeeper and Windows SmartScreen ask before the first run; curl, PowerShell and Homebrew installs are not affected.
Every archive is listed in the release's SHA256SUMS, and you can check it was built by this repository's CI with gh attestation verify supergateway-darwin-arm64.tar.gz -R supercorp-ai/supergateway.
Shutdown
Allow more than five seconds for graceful shutdown. Child servers should handle SIGTERM when you stop the gateway with Ctrl-C.
For network-output gateways, closing a pipe connected to stdin also stops the gateway. Starting with stdin ignored or redirected from /dev/null keeps it running.
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"
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.
Troubleshooting
--baseUrl host is not used
In stdio→SSE mode only the path of --baseUrl reaches clients: --baseUrl https://mcp.example.com/gateway makes the message endpoint /gateway/message, and clients post to the host they connected through. Clients that need an absolute endpoint URL, such as Copilot Studio, should use --outputTransport streamableHttp.
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.
Additional resources
Superargs - provide arguments to MCP servers during runtime.
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.
Two more checks compare this build with the last release, and need the network to fetch it. CI runs both on every pull request:
npm run test:versions # the same client against the release and this build, side by side
npm run test:released # the release's own end-to-end tests, run against this build
A difference that is meant is written down with its reason in tests/crossVersion.intended.ts or tests/releasedTests.intended.json; any other fails.
