📌Overview

Purpose: Supergateway enables seamless execution of MCP stdio-based servers over Server-Sent Events (SSE) or WebSockets (WS), facilitating remote access, debugging, and client connections.

Overview: Supergateway provides a straightforward command-line interface to run and manage MCP servers through SSE and WS protocols. This is particularly advantageous for situations where standard input/output (stdio) servers need to be accessed remotely or integrated into different environments, simplifying the workflow for developers and enhancing server interactions.

Key Features:

• Easy Command Execution: Run MCP servers with a single command using npx, streamlining deployment and configuration for both SSE and WS.

• Flexible Transport Options: Offers support for multiple output transports (stdio, SSE, WS), allowing users to choose the most suitable method for their use case.

• Modular Design: Automates JSON-RPC versioning and retransmits metadata, enabling efficient server management and ease of integration with minimal manual intervention.

• CORS and Health Endpoint Support: Includes options for enabling Cross-Origin Resource Sharing (CORS) and setting health check endpoints, enhancing interoperability and reliability in diverse environments.

---

Supergateway

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"

Options

• --stdio "command": Command that runs an MCP server over stdio.
• --sse "https://...": SSE URL to connect to (SSE→stdio mode).
• --outputTransport stdio | sse | ws: Output MCP transport (default: sse with --stdio, stdio with --sse).
• --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).
• --header "x-user-id: 123": Add one or more headers (stdio→SSE or SSE→stdio mode; can be used multiple times).
• --oauth2Bearer "some-access-token": Adds an Authorization header with the provided Bearer token.
• --logLevel info | none: Controls logging level (default: info). Use 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:

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 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"

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)

1. Run Supergateway:

npx -y supergateway --port 8000 \
    --stdio "npx -y @modelcontextprotocol/server-filesystem /Users/MyName/Desktop"

2. 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 a 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:
supercorp/supergateway on Docker Hub
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

The MCP server runs in the container’s root directory (/). You can mount host directories if needed.

Building the Image Yourself

docker build -t supergateway .

docker run -it --rm -p 8000:8000 supergateway \
    --stdio "npx -y @modelcontextprotocol/server-filesystem /" \
    --port 8000

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 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: To pass an Authorization header with spaces, 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

• 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

• @StefanBurscher
• @tarasyarema
• @pcnfernando
• @Areo-Joe
• @Joffref
• @michaeljguarino

Contributing

Issues and PRs welcome. Please open one if you encounter problems or have feature suggestions.

License

MIT License