Supergateway MCP Proxy

Common errors

• Error: listen EADDRINUSE: address already in use :::8000

  cause The default port 8000 (or another specified port) is already in use by another process on your system.
  fix Specify an unused port using the `--port` flag (e.g., `npx supergateway --port 8001 ...`) or identify and terminate the process currently using the port.

• Connection refused

  cause A client is unable to establish a connection with the Supergateway server, often because the server isn't running, is on a different address/port, or a firewall is blocking the connection.
  fix Verify that Supergateway is running, listening on the expected `--port` and `--baseUrl` (if specified). Check for any active firewalls or network configurations that might be preventing client connections.

• Error: Command 'your-stdio-command-here' not found

  cause The command provided to the `--stdio` flag cannot be found or executed by the operating system.
  fix Ensure the command you pass to `--stdio` (e.g., `uvx mcp-server-git`, `node my-server.js`) is correctly spelled, executable, and present in your system's PATH. Test the command independently in your shell.

Warnings

• breaking Version 3.3.0 introduced significant stability issues related to concurrency improvements, causing some MCP stdio servers to hang. This version was explicitly rolled back in v3.4.0.
  Fix: Avoid using v3.3.0. Upgrade to v3.4.0 or any subsequent stable release (e.g., >=3.4.0) to benefit from the rollback and improved stability.
• gotcha Incorrect or omitted CORS configuration can prevent web clients from connecting due to cross-origin resource sharing policies.
  Fix: Use the `--cors` flag. For all origins, simply use `--cors`. For specific origins, specify them (e.g., `--cors "http://example.com"`). Regex patterns are also supported.
• gotcha Concurrency settings (`--minConcurrency`, `--maxConcurrency`) for stdio-to-SSE mode, while offering performance benefits, can introduce stability issues if not correctly tuned for your specific MCP server.
  Fix: Start with default concurrency (1) and increase incrementally while monitoring server stability and resource usage. Refer to the `--minConcurrency` and `--maxConcurrency` flags in the documentation.
• gotcha When connecting to remote SSE or Streamable HTTP servers that require authentication, forgetting to pass appropriate headers will result in unauthorized access or connection failures.
  Fix: For bearer tokens, use `--oauth2Bearer "your-token"`. For other headers, use `--header "X-Custom-Header: value"`. Multiple `--header` flags can be used.

Install

• npm install supergateway npm
• yarn add supergateway yarn
• pnpm add supergateway pnpm

Imports

• supergateway CLI (stdio to SSE/WS)
  wrong:

  import { Supergateway } from 'supergateway'

  correct:

  npx supergateway --stdio "your-mcp-command" --port 8000

  Supergateway is primarily a command-line interface tool. Its core functionality is exposed via CLI arguments, not through direct module imports in JavaScript/TypeScript code. This pattern exposes a local stdio server over HTTP.
• supergateway CLI (SSE to stdio)
  wrong:

  const gateway = require('supergateway'); gateway.connectSSE(...)

  correct:

  npx supergateway --sse "https://remote-mcp-server.example.com"

  To connect to a remote SSE server and expose its output locally via stdio, use the `--sse` flag. The `--sse` flag implies `stdio` as the output transport if `--outputTransport` is not specified.
• supergateway CLI (Streamable HTTP to stdio)
  wrong:

  npm install supergateway && node_modules/supergateway/cli.js --streamableHttp ...

  correct:

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

  For bridging a remote Streamable HTTP server to local stdio, use the `--streamableHttp` flag. Using `npx` ensures the correct package version is used without global installation issues.

Quickstart

Demonstrates how to run Supergateway to expose a local stdio-based Model Context Protocol (MCP) server as an SSE endpoint, allowing remote clients to interact with it via HTTP.

const { exec } = require('child_process');

// This command starts Supergateway, which in turn runs an MCP server
// (here, a filesystem-based one) and exposes its communication
// via SSE endpoints on localhost:8000.
//
// Clients can then subscribe to events via GET /sse and send messages
// via POST /message to interact with the underlying stdio server.
// Replace 'npx -y @modelcontextprotocol/server-filesystem ./my-folder'
// with your actual MCP stdio server command.
const supergatewayCommand = `npx -y supergateway \n    --stdio "npx -y @modelcontextprotocol/server-filesystem ./my-folder" \n    --port 8000 --baseUrl http://localhost:8000 \n    --ssePath /sse --messagePath /message`;

console.log("To start Supergateway, run this in your terminal:");
console.log(supergatewayCommand);

// Example of how you might programmatically run it in a Node.js script
// (though Supergateway is typically run directly in a shell)
// exec(supergatewayCommand, (error, stdout, stderr) => {
//     if (error) {
//         console.error(`exec error: ${error}`);
//         return;
//     }
//     console.log(`stdout: ${stdout}`);
//     console.error(`stderr: ${stderr}`);
// });

console.log("\nOnce running, you can subscribe to events with: GET http://localhost:8000/sse");
console.log("And send messages with: POST http://localhost:8000/message");