SuperGateway

Converts stdio MCP servers into SSE endpoints for remote access and control

other

6

GitHub Stars

other

Language

6 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "coding-alt-supergateway": {
      "command": "java",
      "args": [
        "-jar",
        "your-mcp-server.jar"
      ]
    }
  }
}

SuperGateway is a gateway tool that converts standard input/output (stdio) MCP servers into a server-sent events (SSE) service. It lets you run MCP servers that communicate over stdio and expose them remotely via SSE, enabling multiple clients to connect, forward JSON outputs, and manage health checks and CORS from a centralized gateway.

How to use

You run your MCP server as a stdio process and connect to it through the gateway. Clients subscribe to the SSE feed to receive the MCP process output, and you can send JSON messages to the running MCP process via the gateway’s message endpoint. This setup supports multiple concurrent clients and automatic JSON handling, with optional health checks and CORS.

How to install

Prerequisites you need before building and running: java 17 or higher and Maven 3.6 or higher.

# Step 1: Build the gateway
cd src/java
mvn clean package

# Step 2: Run the gateway (adjust options as needed)
java -jar target/supergateway-1.0.0.jar [options]

Additional configuration and usage notes

Available command line options let you tailor how the gateway interfaces with your MCP server and how clients connect.

--version
--stdio "java -jar your-mcp-server.jar"
--sse "http://localhost:8000/sse"
--port 8000
--baseUrl http://localhost:8000
--ssePath /sse
--messagePath /message
--logLevel info
--cors false
--healthEndpoint "health" 
--help

SSE connection and messaging endpoints

You can establish an SSE connection to receive the MCP process output and use a JSON POST to send messages to the running MCP process.

# SSE connection URL
GET /sse

# Send a JSON message to a specific session
POST /message?sessionId=<session_id>
Content-Type: application/json
{ "command": {"action": "doSomething"} }

Health checks

If you configure health checks, you can query the gateway to ensure the service is healthy.

GET /health

Notes

The MCP server's output must be valid JSON to be forwarded to SSE clients. 2. Each SSE client receives a unique sessionId. 3. All messages must be valid JSON. 4. When sending messages, use the correct sessionId obtained from the SSE connection. 5. The MCP server must support communication over stdio.

Security considerations

If you enable CORS, make sure you restrict allowed origins to trusted clients. Regularly review your health checks and logging to avoid exposing sensitive information.

Examples

Run a local MCP server and expose it via SSE on port 8000 with default paths for SSE and messages.

java -jar target/supergateway-1.0.0.jar \
  --stdio "java -jar your-mcp-server.jar" \
  --port 8000 \
  --baseUrl http://localhost:8000 \
  --ssePath /sse \
  --messagePath /message

Available tools

sseConnect

Establish an SSE connection to receive real-time MCP process output from the gateway.

sendMessage

Send JSON messages to the running MCP process through the gateway using the /message endpoint.

healthCheck

Check gateway health via the configured health endpoints to verify the MCP service is running correctly.