https://github.com/supercorp-ai/supergateway
Run MCP stdio servers over SSE and SSE over stdio. AI gateway.
https://github.com/supercorp-ai/supergateway
Last synced: 3 days ago
JSON representation
Run MCP stdio servers over SSE and SSE over stdio. AI gateway.
- Host: GitHub
- URL: https://github.com/supercorp-ai/supergateway
- Owner: supercorp-ai
- License: mit
- Created: 2024-12-21T12:23:48.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-10-09T17:05:14.000Z (3 months ago)
- Last Synced: 2025-12-07T14:11:45.148Z (about 1 month ago)
- Language: TypeScript
- Homepage:
- Size: 3.28 MB
- Stars: 2,279
- Watchers: 17
- Forks: 193
- Open Issues: 32
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-llm-services - SuperGateway
- awesome-dotnet-mcp - supergateway - Run MCP stdio servers over SSE and SSE over stdio. AI gateway. (Tools / Official)
- awesome-rainmana - supercorp-ai/supergateway - Run MCP stdio servers over SSE and SSE over stdio. AI gateway. (TypeScript)
README
**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](https://supermachine.ai) (hosted MCPs), [Superinterface](https://superinterface.ai), and [Supercorp](https://supercorp.ai).
## Installation & Usage
Run Supergateway via `npx`:
```bash
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: `sse` with `--stdio`, `stdio` with `--sse` or `--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 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.
- **`--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 (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:
```bash
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:
```bash
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:
```bash
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:
```bash
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:
```bash
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
```bash
npx -y supergateway \
--stdio "npx -y @modelcontextprotocol/server-filesystem ./my-folder" \
--outputTransport streamableHttp \
--port 8000
```
### Stateful mode
```bash
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:
```bash
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)
1. **Run Supergateway**:
```bash
npx -y supergateway --port 8000 \
--stdio "npx -y @modelcontextprotocol/server-filesystem /Users/MyName/Desktop"
```
2. **Use MCP Inspector**:
```bash
npx @modelcontextprotocol/inspector
```
You can now list tools, resources, or perform MCP actions via Supergateway.
## Using with ngrok
Use [ngrok](https://ngrok.com/) to share your local MCP server publicly:
```bash
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](https://hub.docker.com/r/supercorp/supergateway). Also on GHCR: [ghcr.io/supercorp-ai/supergateway](https://github.com/supercorp-ai/supergateway/pkgs/container/supergateway)
### Using the Official Image
```bash
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 `uvx` directly:
```bash
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:
```bash
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:
```bash
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
```json
{
"mcpServers": {
"supermachineExampleNpx": {
"command": "npx",
"args": [
"-y",
"supergateway",
"--sse",
"https://mcp-server-ab71a6b2-cd55-49d0-adba-562bc85956e3.supermachine.app"
]
}
}
}
```
### Docker-based MCP Server Example
```json
{
"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
```json
{
"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
```json
{
"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](https://spec.modelcontextprotocol.io/) 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](https://github.com/supercorp-ai/superargs) - provide arguments to MCP servers during runtime.
## Contributors
- [@longfin](https://github.com/longfin)
- [@griffinqiu](https://github.com/griffinqiu)
- [@folkvir](https://github.com/folkvir)
- [@wizizm](https://github.com/wizizm)
- [@dtinth](https://github.com/dtinth)
- [@rajivml](https://github.com/rajivml)
- [@NicoBonaminio](https://github.com/NicoBonaminio)
- [@sibbl](https://github.com/sibbl)
- [@podarok](https://github.com/podarok)
- [@jmn8718](https://github.com/jmn8718)
- [@TraceIvan](https://github.com/TraceIvan)
- [@zhoufei0622](https://github.com/zhoufei0622)
- [@ezyang](https://github.com/ezyang)
- [@aleksadvaisly](https://github.com/aleksadvaisly)
- [@wuzhuoquan](https://github.com/wuzhuoquan)
- [@mantrakp04](https://github.com/mantrakp04)
- [@mheubi](https://github.com/mheubi)
- [@mjmendo](https://github.com/mjmendo)
- [@CyanMystery](https://github.com/CyanMystery)
- [@earonesty](https://github.com/earonesty)
- [@StefanBurscher](https://github.com/StefanBurscher)
- [@tarasyarema](https://github.com/tarasyarema)
- [@pcnfernando](https://github.com/pcnfernando)
- [@Areo-Joe](https://github.com/Areo-Joe)
- [@Joffref](https://github.com/Joffref)
- [@michaeljguarino](https://github.com/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](https://github.com/nvm-sh/nvm) you can install and activate it with:
```bash
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.
## License
[MIT License](./LICENSE)