{"id":28639462,"url":"https://github.com/supercorp-ai/supergateway","last_synced_at":"2026-01-12T11:27:42.467Z","repository":{"id":269169300,"uuid":"906621484","full_name":"supercorp-ai/supergateway","owner":"supercorp-ai","description":"Run MCP stdio servers over SSE and SSE over stdio. AI gateway.","archived":false,"fork":false,"pushed_at":"2025-10-09T17:05:14.000Z","size":3436,"stargazers_count":2279,"open_issues_count":32,"forks_count":193,"subscribers_count":17,"default_branch":"main","last_synced_at":"2025-12-07T14:11:45.148Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/supercorp-ai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-12-21T12:23:48.000Z","updated_at":"2025-12-07T12:46:06.000Z","dependencies_parsed_at":"2025-01-25T03:22:33.994Z","dependency_job_id":"f73f8d44-8e69-46e8-aaad-7596b1dc4821","html_url":"https://github.com/supercorp-ai/supergateway","commit_stats":null,"previous_names":["supercorp-ai/supergateway"],"tags_count":24,"template":false,"template_full_name":null,"purl":"pkg:github/supercorp-ai/supergateway","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/supercorp-ai%2Fsupergateway","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/supercorp-ai%2Fsupergateway/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/supercorp-ai%2Fsupergateway/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/supercorp-ai%2Fsupergateway/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/supercorp-ai","download_url":"https://codeload.github.com/supercorp-ai/supergateway/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/supercorp-ai%2Fsupergateway/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28338971,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-12T10:58:46.209Z","status":"ssl_error","status_checked_at":"2026-01-12T10:58:42.742Z","response_time":98,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-12T19:40:26.925Z","updated_at":"2026-01-12T11:27:42.459Z","avatar_url":"https://github.com/supercorp-ai.png","language":"TypeScript","funding_links":[],"categories":["TypeScript","\u003cimg src=\"./assets/satellite.svg\" width=\"16\" height=\"16\" style=\"vertical-align: middle;\"\u003e Satellites","Catalog","📚 Projects (1974 total)","Tools","🤖 AI \u0026 Machine Learning","Developer Tools","MCP Servers \u0026 Protocol"],"sub_categories":["agent","MCP Servers","Official"],"readme":"![Supergateway: Run stdio MCP servers over SSE and WS](https://raw.githubusercontent.com/supercorp-ai/supergateway/main/supergateway.png)\n\n**Supergateway** runs **MCP stdio-based servers** over **SSE (Server-Sent Events)** or **WebSockets (WS)** with one command. This is useful for remote access, debugging, or connecting to clients when your MCP server only supports stdio.\n\nSupported by [Supermachine](https://supermachine.ai) (hosted MCPs), [Superinterface](https://superinterface.ai), and [Supercorp](https://supercorp.ai).\n\n## Installation \u0026 Usage\n\nRun Supergateway via `npx`:\n\n```bash\nnpx -y supergateway --stdio \"uvx mcp-server-git\"\n```\n\n- **`--stdio \"command\"`**: Command that runs an MCP server over stdio\n- **`--sse \"https://mcp-server-ab71a6b2-cd55-49d0-adba-562bc85956e3.supermachine.app\"`**: SSE URL to connect to (SSE→stdio mode)\n- **`--streamableHttp \"https://mcp-server.example.com/mcp\"`**: Streamable HTTP URL to connect to (StreamableHttp→stdio mode)\n- **`--outputTransport stdio | sse | ws | streamableHttp`**: Output MCP transport (default: `sse` with `--stdio`, `stdio` with `--sse` or `--streamableHttp`)\n- **`--port 8000`**: Port to listen on (stdio→SSE or stdio→WS mode, default: `8000`)\n- **`--baseUrl \"http://localhost:8000\"`**: Base URL for SSE or WS clients (stdio→SSE mode; optional)\n- **`--ssePath \"/sse\"`**: Path for SSE subscriptions (stdio→SSE mode, default: `/sse`)\n- **`--messagePath \"/message\"`**: Path for messages (stdio→SSE or stdio→WS mode, default: `/message`)\n- **`--streamableHttpPath \"/mcp\"`**: Path for Streamable HTTP (stdio→Streamable HTTP mode, default: `/mcp`)\n- **`--stateful`**: Run stdio→Streamable HTTP in stateful mode\n- **`--sessionTimeout 60000`**: Session timeout in milliseconds (stateful stdio→Streamable HTTP mode only)\n- **`--header \"x-user-id: 123\"`**: Add one or more headers (stdio→SSE, SSE→stdio, or Streamable HTTP→stdio mode; can be used multiple times)\n- **`--oauth2Bearer \"some-access-token\"`**: Adds an `Authorization` header with the provided Bearer token\n- **`--logLevel debug | info | none`**: Controls logging level (default: `info`). Use `debug` for more verbose logs, `none` to suppress all logs.\n- **`--cors`**: Enable CORS (stdio→SSE or stdio→WS mode). Use `--cors` with no values to allow all origins, or supply one or more allowed origins (e.g. `--cors \"http://example.com\"` or `--cors \"/example\\\\.com$/\"` for regex matching).\n- **`--healthEndpoint /healthz`**: Register one or more endpoints (stdio→SSE or stdio→WS mode; can be used multiple times) that respond with `\"ok\"`\n\n## stdio → SSE\n\nExpose an MCP stdio server as an SSE server:\n\n```bash\nnpx -y supergateway \\\n    --stdio \"npx -y @modelcontextprotocol/server-filesystem ./my-folder\" \\\n    --port 8000 --baseUrl http://localhost:8000 \\\n    --ssePath /sse --messagePath /message\n```\n\n- **Subscribe to events**: `GET http://localhost:8000/sse`\n- **Send messages**: `POST http://localhost:8000/message`\n\n## SSE → stdio\n\nConnect to a remote SSE server and expose locally via stdio:\n\n```bash\nnpx -y supergateway --sse \"https://mcp-server-ab71a6b2-cd55-49d0-adba-562bc85956e3.supermachine.app\"\n```\n\nUseful for integrating remote SSE MCP servers into local command-line environments.\n\nYou can also pass headers when sending requests. This is useful for authentication:\n\n```bash\nnpx -y supergateway \\\n    --sse \"https://mcp-server-ab71a6b2-cd55-49d0-adba-562bc85956e3.supermachine.app\" \\\n    --oauth2Bearer \"some-access-token\" \\\n    --header \"X-My-Header: another-header-value\"\n```\n\n## Streamable HTTP → stdio\n\nConnect to a remote Streamable HTTP server and expose locally via stdio:\n\n```bash\nnpx -y supergateway --streamableHttp \"https://mcp-server.example.com/mcp\"\n```\n\nThis mode is useful for connecting to MCP servers that use the newer Streamable HTTP transport protocol. Like SSE mode, you can also pass headers for authentication:\n\n```bash\nnpx -y supergateway \\\n    --streamableHttp \"https://mcp-server.example.com/mcp\" \\\n    --oauth2Bearer \"some-access-token\" \\\n    --header \"X-My-Header: another-header-value\"\n```\n\n## stdio → Streamable HTTP\n\nExpose an MCP stdio server as a Streamable HTTP server.\n\n### Stateless mode\n\n```bash\nnpx -y supergateway \\\n    --stdio \"npx -y @modelcontextprotocol/server-filesystem ./my-folder\" \\\n    --outputTransport streamableHttp \\\n    --port 8000\n```\n\n### Stateful mode\n\n```bash\nnpx -y supergateway \\\n    --stdio \"npx -y @modelcontextprotocol/server-filesystem ./my-folder\" \\\n    --outputTransport streamableHttp --stateful \\\n    --sessionTimeout 60000 --port 8000\n```\n\nThe Streamable HTTP endpoint defaults to `http://localhost:8000/mcp` (configurable via `--streamableHttpPath`).\n\n## stdio → WS\n\nExpose an MCP stdio server as a WebSocket server:\n\n```bash\nnpx -y supergateway \\\n    --stdio \"npx -y @modelcontextprotocol/server-filesystem ./my-folder\" \\\n    --port 8000 --outputTransport ws --messagePath /message\n```\n\n- **WebSocket endpoint**: `ws://localhost:8000/message`\n\n## Example with MCP Inspector (stdio → SSE mode)\n\n1. **Run Supergateway**:\n\n```bash\nnpx -y supergateway --port 8000 \\\n    --stdio \"npx -y @modelcontextprotocol/server-filesystem /Users/MyName/Desktop\"\n```\n\n2. **Use MCP Inspector**:\n\n```bash\nnpx @modelcontextprotocol/inspector\n```\n\nYou can now list tools, resources, or perform MCP actions via Supergateway.\n\n## Using with ngrok\n\nUse [ngrok](https://ngrok.com/) to share your local MCP server publicly:\n\n```bash\nnpx -y supergateway --port 8000 --stdio \"npx -y @modelcontextprotocol/server-filesystem .\"\n\n# In another terminal:\nngrok http 8000\n```\n\nngrok provides a public URL for remote access.\n\nMCP server will be available at URL similar to: https://1234-567-890-12-456.ngrok-free.app/sse\n\n## Running with Docker\n\nA Docker-based workflow avoids local Node.js setup. A ready-to-run Docker image is available here:\n[supercorp/supergateway](https://hub.docker.com/r/supercorp/supergateway). Also on GHCR: [ghcr.io/supercorp-ai/supergateway](https://github.com/supercorp-ai/supergateway/pkgs/container/supergateway)\n\n### Using the Official Image\n\n```bash\ndocker run -it --rm -p 8000:8000 supercorp/supergateway \\\n    --stdio \"npx -y @modelcontextprotocol/server-filesystem /\" \\\n    --port 8000\n```\n\nDocker pulls the image automatically. The MCP server runs in the container’s root directory (`/`). You can mount host directories if needed.\n\n#### Images with dependencies\n\nPull any of these pre-built Supergateway images for various dependencies you might need.\n\n- **uvx**\n  Supergateway + uv/uvx, so you can call `uvx` directly:\n\n  ```bash\n  docker run -it --rm -p 8000:8000 supercorp/supergateway:uvx \\\n    --stdio \"uvx mcp-server-fetch\"\n  ```\n\n- **deno**\n  Supergateway + Deno, ready to run Deno-based MCP servers:\n  ```bash\n  docker run -it --rm -p 8000:8000 supercorp/supergateway:deno \\\n    --stdio \"deno run -A jsr:@omedia/mcp-server-drupal --drupal-url https://your-drupal-server.com\"\n  ```\n\n### Building the Image Yourself\n\nUse provided Dockerfile:\n\n```bash\ndocker build -f docker/base.Dockerfile -t supergateway .\n\ndocker run -it --rm -p 8000:8000 supergateway --stdio \"npx -y @modelcontextprotocol/server-filesystem .\"\n```\n\n## Using with Claude Desktop (SSE → stdio mode)\n\nClaude Desktop can use Supergateway’s SSE→stdio mode.\n\n### NPX-based MCP Server Example\n\n```json\n{\n  \"mcpServers\": {\n    \"supermachineExampleNpx\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"supergateway\",\n        \"--sse\",\n        \"https://mcp-server-ab71a6b2-cd55-49d0-adba-562bc85956e3.supermachine.app\"\n      ]\n    }\n  }\n}\n```\n\n### Docker-based MCP Server Example\n\n```json\n{\n  \"mcpServers\": {\n    \"supermachineExampleDocker\": {\n      \"command\": \"docker\",\n      \"args\": [\n        \"run\",\n        \"-i\",\n        \"--rm\",\n        \"supercorp/supergateway\",\n        \"--sse\",\n        \"https://mcp-server-ab71a6b2-cd55-49d0-adba-562bc85956e3.supermachine.app\"\n      ]\n    }\n  }\n}\n```\n\n## Using with Cursor (SSE → stdio mode)\n\nCursor can also integrate with Supergateway in SSE→stdio mode. The configuration is similar to Claude Desktop.\n\n### NPX-based MCP Server Example for Cursor\n\n```json\n{\n  \"mcpServers\": {\n    \"cursorExampleNpx\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"supergateway\",\n        \"--sse\",\n        \"https://mcp-server-ab71a6b2-cd55-49d0-adba-562bc85956e3.supermachine.app\"\n      ]\n    }\n  }\n}\n```\n\n### Docker-based MCP Server Example for Cursor\n\n```json\n{\n  \"mcpServers\": {\n    \"cursorExampleDocker\": {\n      \"command\": \"docker\",\n      \"args\": [\n        \"run\",\n        \"-i\",\n        \"--rm\",\n        \"supercorp/supergateway\",\n        \"--sse\",\n        \"https://mcp-server-ab71a6b2-cd55-49d0-adba-562bc85956e3.supermachine.app\"\n      ]\n    }\n  }\n}\n```\n\n**Note:** Although the setup supports sending headers via the `--header` flag, if you need to pass an Authorization header (which typically includes a space, e.g. `\"Bearer 123\"`), you must use the `--oauth2Bearer` flag due to a known Cursor bug with spaces in command-line arguments.\n\n## Why MCP?\n\n[Model Context Protocol](https://spec.modelcontextprotocol.io/) standardizes AI tool interactions. Supergateway converts MCP stdio servers into SSE or WS services, simplifying integration and debugging with web-based or remote clients.\n\n## Advanced Configuration\n\nSupergateway emphasizes modularity:\n\n- Automatically manages JSON-RPC versioning.\n- Retransmits package metadata where possible.\n- stdio→SSE or stdio→WS mode logs via standard output; SSE→stdio mode logs via stderr.\n\n## Additional resources\n\n- [Superargs](https://github.com/supercorp-ai/superargs) - provide arguments to MCP servers during runtime.\n\n## Contributors\n\n- [@longfin](https://github.com/longfin)\n- [@griffinqiu](https://github.com/griffinqiu)\n- [@folkvir](https://github.com/folkvir)\n- [@wizizm](https://github.com/wizizm)\n- [@dtinth](https://github.com/dtinth)\n- [@rajivml](https://github.com/rajivml)\n- [@NicoBonaminio](https://github.com/NicoBonaminio)\n- [@sibbl](https://github.com/sibbl)\n- [@podarok](https://github.com/podarok)\n- [@jmn8718](https://github.com/jmn8718)\n- [@TraceIvan](https://github.com/TraceIvan)\n- [@zhoufei0622](https://github.com/zhoufei0622)\n- [@ezyang](https://github.com/ezyang)\n- [@aleksadvaisly](https://github.com/aleksadvaisly)\n- [@wuzhuoquan](https://github.com/wuzhuoquan)\n- [@mantrakp04](https://github.com/mantrakp04)\n- [@mheubi](https://github.com/mheubi)\n- [@mjmendo](https://github.com/mjmendo)\n- [@CyanMystery](https://github.com/CyanMystery)\n- [@earonesty](https://github.com/earonesty)\n- [@StefanBurscher](https://github.com/StefanBurscher)\n- [@tarasyarema](https://github.com/tarasyarema)\n- [@pcnfernando](https://github.com/pcnfernando)\n- [@Areo-Joe](https://github.com/Areo-Joe)\n- [@Joffref](https://github.com/Joffref)\n- [@michaeljguarino](https://github.com/michaeljguarino)\n\n## Contributing\n\nIssues and PRs welcome. Please open one if you encounter problems or have feature suggestions.\n\n## Tests\n\nSupergateway is tested with the Node Test Runner.\n\nTo run the suite locally you need Node **24+**. Using [nvm](https://github.com/nvm-sh/nvm) you can install and activate it with:\n\n```bash\nnvm install 24\nnvm use 24\nnpm install\nnpm run build\nnpm test\n```\n\nThe `tests/helpers/mock-mcp-server.js` script provides a local MCP server so all\ntests run without network access.\n\n## License\n\n[MIT License](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsupercorp-ai%2Fsupergateway","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsupercorp-ai%2Fsupergateway","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsupercorp-ai%2Fsupergateway/lists"}