{"id":17374,"library":"supergateway","title":"Supergateway MCP Proxy","description":"Supergateway is a command-line utility designed to bridge Model Context Protocol (MCP) stdio-based servers with network transports like Server-Sent Events (SSE), WebSockets (WS), and Streamable HTTP, and vice versa. It enables remote access, debugging, and client connectivity for MCP servers that primarily support stdio. The current stable version is 3.4.3. The project demonstrates a relatively active release cadence, with several minor updates and a significant rollback release (v3.4.0) to address stability issues from v3.3.0. Its key differentiator is providing a flexible gateway for various MCP communication patterns, facilitating integration of local stdio services into web-based or distributed systems. It supports both stateless and stateful operations for Streamable HTTP, and offers configurable concurrency for stdio-to-SSE gateways.","status":"active","version":"3.4.3","language":"javascript","source_language":"en","source_url":"https://github.com/supercorp-ai/supergateway","tags":["javascript","mcp","stdio","sse","gateway","proxy","bridge"],"install":[{"cmd":"npm install supergateway","lang":"bash","label":"npm"},{"cmd":"yarn add supergateway","lang":"bash","label":"yarn"},{"cmd":"pnpm add supergateway","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Internal dependency for interacting with Model Context Protocol standards, updated in various minor versions.","package":"@modelcontextprotocol/sdk","optional":false}],"imports":[{"note":"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.","wrong":"import { Supergateway } from 'supergateway'","symbol":"supergateway CLI (stdio to SSE/WS)","correct":"npx supergateway --stdio \"your-mcp-command\" --port 8000"},{"note":"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.","wrong":"const gateway = require('supergateway'); gateway.connectSSE(...)","symbol":"supergateway CLI (SSE to stdio)","correct":"npx supergateway --sse \"https://remote-mcp-server.example.com\""},{"note":"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.","wrong":"npm install supergateway && node_modules/supergateway/cli.js --streamableHttp ...","symbol":"supergateway CLI (Streamable HTTP to stdio)","correct":"npx supergateway --streamableHttp \"https://remote-mcp-server.example.com/mcp\""}],"quickstart":{"code":"const { exec } = require('child_process');\n\n// This command starts Supergateway, which in turn runs an MCP server\n// (here, a filesystem-based one) and exposes its communication\n// via SSE endpoints on localhost:8000.\n//\n// Clients can then subscribe to events via GET /sse and send messages\n// via POST /message to interact with the underlying stdio server.\n// Replace 'npx -y @modelcontextprotocol/server-filesystem ./my-folder'\n// with your actual MCP stdio server command.\nconst 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`;\n\nconsole.log(\"To start Supergateway, run this in your terminal:\");\nconsole.log(supergatewayCommand);\n\n// Example of how you might programmatically run it in a Node.js script\n// (though Supergateway is typically run directly in a shell)\n// exec(supergatewayCommand, (error, stdout, stderr) => {\n//     if (error) {\n//         console.error(`exec error: ${error}`);\n//         return;\n//     }\n//     console.log(`stdout: ${stdout}`);\n//     console.error(`stderr: ${stderr}`);\n// });\n\nconsole.log(\"\\nOnce running, you can subscribe to events with: GET http://localhost:8000/sse\");\nconsole.log(\"And send messages with: POST http://localhost:8000/message\");\n","lang":"javascript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"3.3.0"},{"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.","message":"Incorrect or omitted CORS configuration can prevent web clients from connecting due to cross-origin resource sharing policies.","severity":"gotcha","affected_versions":">=2.7.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=3.3.0"},{"fix":"For bearer tokens, use `--oauth2Bearer \"your-token\"`. For other headers, use `--header \"X-Custom-Header: value\"`. Multiple `--header` flags can be used.","message":"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.","severity":"gotcha","affected_versions":">=2.7.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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.","cause":"The default port 8000 (or another specified port) is already in use by another process on your system.","error":"Error: listen EADDRINUSE: address already in use :::8000"},{"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.","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.","error":"Connection refused"},{"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.","cause":"The command provided to the `--stdio` flag cannot be found or executed by the operating system.","error":"Error: Command 'your-stdio-command-here' not found"}],"ecosystem":"npm","meta_description":null}