Gateway MCP Server

How to use

You can run an MCP stdio server locally and expose it via SSE or WebSockets, or connect to remote MCP servers that use SSE or Streamable HTTP transports. Use the local stdio command to start your MCP server, then pick the transport you want to expose it with. For remote MCP servers, you can connect via SSE or Streamable HTTP and bridge them to local stdio as needed. You can also expose a local MCP server through a public tunnel tool like ngrok if you want external access.

Practical patterns you’ll commonly use include: starting a local MCP server in stdio mode and exporting it via SSE, or connecting to a remote SSE server and exporting it locally via stdio. If you need to share a local MCP server to the internet, run the gateway on a public URL and point clients to the SSE endpoint. For authenticated connections, you can supply bearer tokens or headers as part of the gateway options.

How to install

Prerequisites you need before you begin: node and npm (or a compatible runtime for your setup). Ensure you have Node.js version that supports the MEC of your MCP setup (the typical baseline used in examples is Node 18+ or Node 24+ for tests). Then install or run the gateway using the provided one-liner commands.

Step-by-step commands you can follow: 1) Install and run an MCP stdio server locally via the gateway: 2) Use a local filesystem MCP server as the backend for stdio → SSE: 3) Alternatively, connect to a remote SSE MCP server and expose it locally via stdio: 4) If you want to expose a local MCP server via a Streamable HTTP transport, configure the gateway accordingly. The exact command patterns are shown in the examples below for your reference.

stdio → SSE

Expose an MCP stdio server as an SSE server by running a gateway that starts your local MCP server and serves events over SSE.

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

SSE → stdio

Connect to a remote SSE MCP server and expose locally via stdio.

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

Streamable HTTP → stdio

Connect to a remote Streamable HTTP MCP server and expose locally via stdio. You can pass authentication headers as needed.

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

stdio → Streamable HTTP

Expose a local stdio MCP server as a Streamable HTTP server. Choose stateless or stateful mode depending on your needs.

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

stdio → WS

Expose a local stdio MCP server as a WebSocket server.

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

Example with MCP Inspector (stdio → SSE mode)

You can use a tooling component to inspect MCP resources via Supergateway.

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

Using with ngrok

Share your local MCP gateway publicly using ngrok.

npx -y supergateway --port 8000 --stdio "npx -y @modelcontextprotocol/server-filesystem ."

# In another terminal:
gnrok http 8000

Running with Docker

Use Docker to run Supergateway without installing Node locally. See official images for different dependency stacks.

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

Using with Claude Desktop (SSE → stdio mode)

Claude Desktop can integrate with Supergateway in SSE→stdio mode.

{
  "mcpServers": {
    "supermachineExampleNpx": {
      "command": "npx",
      "args": [
        "-y",
        "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 using similar configurations.

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

Note on headers and authorization

If you need to pass an Authorization header with a space in the value, use the oauth2Bearer option instead of header to avoid command-line parsing issues.

Why MCP

MCP provides a standardized way to describe actions and data interactions for AI tools. Supergateway acts as a bridge, converting MCP stdio servers into web-accessible endpoints for easy testing and debugging.

Advanced configuration

The gateway supports automatic JSON-RPC versioning, retransmission of package metadata, and logging behavior that separates stdio→SSE/WS logs (to stdout) from SSE→stdio logs (to stderr). You can adjust log level, enable CORS, and register health endpoints as needed.

Additional resources

Superargs lets you pass arguments to MCP servers at runtime.

Contributors

The project credits numerous contributors for its development and maintenance.

MCP Inspector

Tools for listing MCP resources, inspecting available MCP actions, and performing MCP-related operations via Supergateway.

ngrok

Publicly expose your local MCP gateway by creating a public URL that tunnels to your localhost.

Superargs

Provide runtime arguments to MCP servers through a centralized mechanism.