Labsco
supercorp-ai logo

Supergateway

★ 2,700

from supercorp-ai

A gateway to run MCP stdio servers over various transports like SSE, WebSockets, and Streamable HTTP.

🔥🔥🔥🔥✓ VerifiedFreeQuick setup
#automation#devops#git

Supergateway: Run stdio MCP servers over SSE and WS

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.

stdio → SSE

Expose an MCP stdio server as an SSE server:

Copy & paste — that's it
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:

Copy & paste — that's it
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:

Copy & paste — that's it
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:

Copy & paste — that's it
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:

Copy & paste — that's it
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

Copy & paste — that's it
npx -y supergateway \
    --stdio "npx -y @modelcontextprotocol/server-filesystem ./my-folder" \
    --outputTransport streamableHttp \
    --port 8000

Stateful mode

Copy & paste — that's it
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:

Copy & paste — that's it
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:
Copy & paste — that's it
npx -y supergateway --port 8000 \
    --stdio "npx -y @modelcontextprotocol/server-filesystem /Users/MyName/Desktop"
  1. Use MCP Inspector:
Copy & paste — that's it
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:

Copy & paste — that's it
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

Using with Claude Desktop (SSE → stdio mode)

Claude Desktop can use Supergateway’s SSE→stdio mode.

NPX-based MCP Server Example

Copy & paste — that's it
{
  "mcpServers": {
    "supermachineExampleNpx": {
      "command": "npx",
      "args": [
        "-y",
        "supergateway",
        "--sse",
        "https://mcp-server-ab71a6b2-cd55-49d0-adba-562bc85956e3.supermachine.app"
      ]
    }
  }
}

Docker-based MCP Server Example

Copy & paste — that's it
{
  "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

Copy & paste — that's it
{
  "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

Copy & paste — that's it
{
  "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.

Additional resources

  • Superargs - provide arguments to MCP servers during runtime.

Contributors

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:

Copy & paste — that's it
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