📌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 facilitates remote access, debugging, or client connections for MCP servers that only support stdio.

Supported by Supermachine, Superinterface, and Supercorp.

Installation & Usage

Run Supergateway via npx:

npx -y supergateway --stdio "uvx mcp-server-git"

Command Options

--stdio "command": Command that runs an MCP server over stdio.
--sse "URL": 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 (default: 8000).
--baseUrl "URL": Base URL for SSE or WS clients (optional).
--ssePath "/sse": Path for SSE subscriptions (default: /sse).
--messagePath "/message": Path for messages (default: /message).
--logLevel info | none: Controls logging level (default: info).
--cors: Enable CORS.
--healthEndpoint /healthz: Register health endpoint(s).

Modes of Operation

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 it locally via stdio:

npx -y supergateway --sse "https://mcp-server-url"

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

Run Supergateway:

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

Use MCP Inspector:

npx @modelcontextprotocol/inspector

Now you can list tools and perform MCP actions.

Using with ngrok

You can 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

Running with Docker

A Docker workflow avoids local Node.js setup. Use the official Docker image:

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

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)

NPX-based MCP Server Example

{
  "mcpServers": {
    "supermachineExampleNpx": {
      "command": "npx",
      "args": [
        "-y",
        "supergateway",
        "--sse",
        "https://mcp-server-url"
      ]
    }
  }
}

Docker-based MCP Server Example

{
  "mcpServers": {
    "supermachineExampleDocker": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "supercorp/supergateway",
        "--sse",
        "https://mcp-server-url"
      ]
    }
  }
}

Why MCP?

Model Context Protocol standardizes AI tool interactions. Supergateway converts MCP stdio servers into SSE or WS services, simplifying integration and debugging.

Advanced Configuration

Supergateway manages:

JSON-RPC versioning.
Package metadata retransmission.
Logging via standard output or stderr based on the mode.

Additional Resources

Superargs - Provides arguments to MCP servers during runtime.

Contributors

Contributing

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

License

MIT License