supergateway

Add Supergateway to your claude_desktop_config.json to use remote SSE MCP servers.

{
  "mcpServers": {
    "supermachineExampleNpx": {
      "command": "npx",
      "args": [
        "-y",
        "supergateway",
        "--sse",
        "https://mcp-server-ab71a6b2-cd55-49d0-adba-562bc85956e3.supermachine.app"
      ]
    }
  }
}

Use this mode to make a local stdio-based MCP server accessible over the network via Server-Sent Events.

• Subscribe to events: GET <baseUrl><ssePath>
• Send messages: POST <baseUrl><messagePath>

npx -y supergateway \
    --stdio "npx -y @modelcontextprotocol/server-filesystem ./my-folder" \
    --port 8000 --baseUrl http://localhost:8000 \
    --ssePath /sse --messagePath /message

Use Docker to run Supergateway without local Node.js setup. You can use the base image or specialized images for uvx or deno dependencies.

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

# Image with uvx support
docker run -it --rm -p 8000:8000 supercorp/supergateway:uvx \
    --stdio "uvx mcp-server-fetch"

# Image with Deno support
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"

Use this mode to connect to a remote MCP server running over SSE and expose it locally as a stdio server. This is useful for integrating remote servers into local CLI environments or tools like Claude Desktop.

npx -y supergateway --sse "https://mcp-server-ab71a6b2-cd55-49d0-adba-562bc85956e3.supermachine.app"

Connect to a remote MCP server using the Streamable HTTP transport protocol and expose it locally via stdio.

npx -y supergateway --streamableHttp "https://mcp-server.example.com/mcp"

The quickest way to use Supergateway is via npx. It allows you to run MCP stdio-based servers over SSE or WebSockets with a single command.

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

Add Supergateway to your Cursor MCP settings.

Important Note: If you need to pass an Authorization header (e.g., "Bearer 123"), you must use the --oauth2Bearer flag instead of --header due to a known Cursor bug regarding spaces in command-line arguments.

{
  "mcpServers": {
    "cursorExampleNpx": {
      "command": "npx",
      "args": [
        "-y",
        "supergateway",
        "--sse",
        "https://mcp-server-ab71a6b2-cd55-49d0-adba-562bc85956e3.supermachine.app"
      ]
    }
  }
}

You can expose a local stdio server as Streamable HTTP in either Stateless or Stateful mode.

Stateless mode:

npx -y supergateway --stdio "npx -y @modelcontextprotocol/server-filesystem ./my-folder" --outputTransport streamableHttp --port 8000

Stateful mode (requires --sessionTimeout):

npx -y supergateway --stdio "npx -y @modelcontextprotocol/server-filesystem ./my-folder" --outputTransport streamableHttp --stateful --sessionTimeout 60000 --port 8000

Expose a local stdio server as a WebSocket server. The WebSocket endpoint will be at the path specified by --messagePath.

npx -y supergateway \
    --stdio "npx -y @modelcontextprotocol/server-filesystem ./my-folder" \
    --port 8000 --outputTransport ws --messagePath /message

Supergateway is a CLI tool used to convert between different Model Context Protocol (MCP) transports, such as converting a local stdio server to an SSE or WS endpoint, or connecting to a remote SSE server via stdio.

To use it, you must specify exactly one input transport using one of the following flags:

• --stdio <command>: Run a local MCP server via a command.
• --sse <url>: Connect to a remote SSE-based MCP server.
• --streamableHttp <url>: Connect to a remote Streamable HTTP-based MCP server.

The gateway uses standard HTTP methods to manage MCP sessions:

• POST {streamableHttpPath}: Used for client-to-server communication. If no mcp-session-id is provided and the body is an initialization request, a new session and child process are created. If a valid mcp-session-id is provided, the existing session is reused.
• GET {streamableHttpPath}: Used for server-to-client notifications via SSE (Server-Sent Events). Requires a valid mcp-session-id header.
• DELETE {streamableHttpPath}: Used to terminate a session and kill the associated child process. Requires a valid mcp-session-id header.

Headers:

• mcp-session-id: Required for reusing or managing existing sessions.
• Mcp-Session-Id: Exposed via CORS for clients to discover their session ID.