{"_id":"@alexissinglaire/supergateway","name":"@alexissinglaire/supergateway","dist-tags":{"latest":"2.7.0"},"versions":{"2.7.0":{"name":"@alexissinglaire/supergateway","version":"2.7.0","description":"Run MCP stdio servers over SSE or visa versa","author":{"name":"Alexis Singlaire"},"homepage":"https://alleluia.com","repository":{"type":"git","url":"git+https://github.com/alexissinglaire/supergateway.git"},"keywords":["mcp","stdio","sse","gateway","proxy","bridge"],"type":"module","bin":{"supergateway":"dist/index.js"},"scripts":{"build":"tsc","start":"node dist/index.js","format":"prettier --write 'src/**/*.ts' '*.json' '.prettierrc'","format:check":"prettier --check 'src/**/*.ts' '*.json' '.prettierrc'","prepare":"husky"},"lint-staged":{"**/*":"prettier --write --ignore-unknown"},"dependencies":{"@modelcontextprotocol/sdk":"^1.4.1","body-parser":"^1.20.3","cors":"^2.8.5","express":"^4.21.2","user":"^0.0.0","uuid":"^11.1.0","ws":"^8.18.1","yargs":"^17.7.2","zod":"^3.24.2"},"devDependencies":{"@types/body-parser":"^1.19.5","@types/cors":"^2.8.17","@types/express":"^5.0.0","@types/node":"^22.13.0","@types/ws":"^8.18.0","@types/yargs":"^17.0.33","husky":"^9.1.7","lint-staged":"^15.5.0","prettier":"^3.5.3","ts-node":"^10.9.2","tsx":"^4.19.2","typescript":"^5.7.3"},"_id":"@alexissinglaire/supergateway@2.7.0","gitHead":"04ff7d6fc12908a86efc60d0be59b42588b30018","bugs":{"url":"https://github.com/alexissinglaire/supergateway/issues"},"_nodeVersion":"22.14.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-8tK1k2siejt0DIMKv5wzGrPz7YxDBxLcwLf2R1mE5nQf45d4oX+usoLWsjcfE5VJo+b173cfvS2iektlHtyU1Q==","shasum":"3cd15e69c5fd7d26b0e9e0957026367ceeb327f9","tarball":"https://registry.npmjs.org/@alexissinglaire/supergateway/-/supergateway-2.7.0.tgz","fileCount":28,"unpackedSize":598586,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIHkWwAvhoxRYaMfHNJ6eFrPP9rgpeUMucxJgIw8eqTi3AiAKnSmFuVWVzo+4FeB6uti2gPxQcPrAXxOaIx+Wh9Ookw=="}]},"_npmUser":{"name":"alexissinglaire","email":"alexissinglaire@gmail.com"},"directories":{},"maintainers":[{"name":"alexissinglaire","email":"alexissinglaire@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/supergateway_2.7.0_1744360633799_0.9924223405108983"},"_hasShrinkwrap":false}},"time":{"created":"2025-04-11T08:37:13.615Z","2.7.0":"2025-04-11T08:37:14.058Z","modified":"2025-04-11T08:37:14.391Z"},"maintainers":[{"name":"alexissinglaire","email":"alexissinglaire@gmail.com"}],"description":"Run MCP stdio servers over SSE or visa versa","homepage":"https://alleluia.com","keywords":["mcp","stdio","sse","gateway","proxy","bridge"],"repository":{"type":"git","url":"git+https://github.com/alexissinglaire/supergateway.git"},"author":{"name":"Alexis Singlaire"},"bugs":{"url":"https://github.com/alexissinglaire/supergateway/issues"},"readme":"![Supergateway: Run stdio MCP servers over SSE and WS](https://raw.githubusercontent.com/supercorp-ai/supergateway/main/supergateway.png)\r\n\r\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.\r\n\r\nSupported by [Supermachine](https://supermachine.ai) (hosted MCPs), [Superinterface](https://superinterface.ai), and [Supercorp](https://supercorp.ai).\r\n\r\n## Installation & Usage\r\n\r\nRun Supergateway via `npx`:\r\n\r\n```bash\r\nnpx -y supergateway --stdio \"uvx mcp-server-git\"\r\n```\r\n\r\n- **`--stdio \"command\"`**: Command that runs an MCP server over stdio\r\n- **`--sse \"https://mcp-server-ab71a6b2-cd55-49d0-adba-562bc85956e3.supermachine.app\"`**: SSE URL to connect to (SSE→stdio mode)\r\n- **`--outputTransport stdio | sse | ws`**: Output MCP transport (default: `sse` with `--stdio`, `stdio` with `--sse`)\r\n- **`--port 8000`**: Port to listen on (stdio→SSE or stdio→WS mode, default: `8000`)\r\n- **`--baseUrl \"http://localhost:8000\"`**: Base URL for SSE or WS clients (stdio→SSE mode; optional)\r\n- **`--ssePath \"/sse\"`**: Path for SSE subscriptions (stdio→SSE mode, default: `/sse`)\r\n- **`--messagePath \"/message\"`**: Path for messages (stdio→SSE or stdio→WS mode, default: `/message`)\r\n- **`--header \"Authorization: Bearer 123\"`**: Add one or more headers (stdio→SSE or SSE→stdio mode; can be used multiple times)\r\n- **`--logLevel info | none`**: Controls logging level (default: `info`). Use `none` to suppress all logs.\r\n- **`--cors`**: Enable CORS (stdio→SSE or stdio→WS mode)\r\n- **`--healthEndpoint /healthz`**: Register one or more endpoints (stdio→SSE or stdio→WS mode; can be used multiple times) that respond with `\"ok\"`\r\n\r\n## stdio → SSE\r\n\r\nExpose an MCP stdio server as an SSE server:\r\n\r\n```bash\r\nnpx -y supergateway \\\r\n    --stdio \"npx -y @modelcontextprotocol/server-filesystem ./my-folder\" \\\r\n    --port 8000 --baseUrl http://localhost:8000 \\\r\n    --ssePath /sse --messagePath /message\r\n```\r\n\r\n- **Subscribe to events**: `GET http://localhost:8000/sse`\r\n- **Send messages**: `POST http://localhost:8000/message`\r\n\r\n## SSE → stdio\r\n\r\nConnect to a remote SSE server and expose locally via stdio:\r\n\r\n```bash\r\nnpx -y supergateway --sse \"https://mcp-server-ab71a6b2-cd55-49d0-adba-562bc85956e3.supermachine.app\"\r\n```\r\n\r\nUseful for integrating remote SSE MCP servers into local command-line environments.\r\n\r\nYou can also pass headers when sending requests. This is useful for authentication:\r\n\r\n```bash\r\nnpx -y supergateway \\\r\n    --sse \"https://mcp-server-ab71a6b2-cd55-49d0-adba-562bc85956e3.supermachine.app\" \\\r\n    --header \"Authorization: Bearer some-token\" \\\r\n    --header \"X-My-Header: another-value\"\r\n```\r\n\r\n## stdio → WS\r\n\r\nExpose an MCP stdio server as a WebSocket server:\r\n\r\n```bash\r\nnpx -y supergateway \\\r\n    --stdio \"npx -y @modelcontextprotocol/server-filesystem ./my-folder\" \\\r\n    --port 8000 --outputTransport ws --messagePath /message\r\n```\r\n\r\n- **WebSocket endpoint**: `ws://localhost:8000/message`\r\n\r\n## Example with MCP Inspector (stdio → SSE mode)\r\n\r\n1. **Run Supergateway**:\r\n\r\n```bash\r\nnpx -y supergateway --port 8000 \\\r\n    --stdio \"npx -y @modelcontextprotocol/server-filesystem /Users/MyName/Desktop\"\r\n```\r\n\r\n2. **Use MCP Inspector**:\r\n\r\n```bash\r\nnpx @modelcontextprotocol/inspector\r\n```\r\n\r\nYou can now list tools, resources, or perform MCP actions via Supergateway.\r\n\r\n## Using with ngrok\r\n\r\nUse [ngrok](https://ngrok.com/) to share your local MCP server publicly:\r\n\r\n```bash\r\nnpx -y supergateway --port 8000 \\\r\n    --stdio \"npx -y @modelcontextprotocol/server-filesystem .\"\r\n\r\n# In another terminal:\r\nngrok http 8000\r\n```\r\n\r\nngrok provides a public URL for remote access.\r\n\r\n## Running with Docker\r\n\r\nA Docker-based workflow avoids local Node.js setup. A ready-to-run Docker image is available here:\r\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)\r\n\r\n### Using the Official Image\r\n\r\n```bash\r\ndocker run -it --rm -p 8000:8000 supercorp/supergateway \\\r\n    --stdio \"npx -y @modelcontextprotocol/server-filesystem /\" \\\r\n    --port 8000\r\n```\r\n\r\nDocker pulls the image automatically. The MCP server runs in the container’s root directory (`/`). You can mount host directories if needed.\r\n\r\n### Building the Image Yourself\r\n\r\nUse provided Dockerfile:\r\n\r\n```bash\r\ndocker build -t supergateway .\r\n\r\ndocker run -it --rm -p 8000:8000 supergateway \\\r\n    --stdio \"npx -y @modelcontextprotocol/server-filesystem /\" \\\r\n    --port 8000\r\n```\r\n\r\n## Using with Claude Desktop (SSE → stdio mode)\r\n\r\nClaude Desktop can use Supergateway’s SSE→stdio mode.\r\n\r\n### NPX-based MCP Server Example\r\n\r\n```json\r\n{\r\n  \"mcpServers\": {\r\n    \"supermachineExampleNpx\": {\r\n      \"command\": \"npx\",\r\n      \"args\": [\r\n        \"-y\",\r\n        \"supergateway\",\r\n        \"--sse\",\r\n        \"https://mcp-server-ab71a6b2-cd55-49d0-adba-562bc85956e3.supermachine.app\"\r\n      ]\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n### Docker-based MCP Server Example\r\n\r\n```json\r\n{\r\n  \"mcpServers\": {\r\n    \"supermachineExampleDocker\": {\r\n      \"command\": \"docker\",\r\n      \"args\": [\r\n        \"run\",\r\n        \"-i\",\r\n        \"--rm\",\r\n        \"supercorp/supergateway\",\r\n        \"--sse\",\r\n        \"https://mcp-server-ab71a6b2-cd55-49d0-adba-562bc85956e3.supermachine.app\"\r\n      ]\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n## Why MCP?\r\n\r\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.\r\n\r\n## Advanced Configuration\r\n\r\nSupergateway emphasizes modularity:\r\n\r\n- Automatically manages JSON-RPC versioning.\r\n- Retransmits package metadata where possible.\r\n- stdio→SSE or stdio→WS mode logs via standard output; SSE→stdio mode logs via stderr.\r\n\r\n## Additional resources\r\n\r\n- [Superargs](https://github.com/supercorp-ai/superargs) - provide arguments to MCP servers during runtime.\r\n\r\n## Contributors\r\n\r\n- [@pcnfernando](https://github.com/pcnfernando)\r\n- [@Areo-Joe](https://github.com/Areo-Joe)\r\n- [@Joffref](https://github.com/Joffref)\r\n- [@michaeljguarino](https://github.com/michaeljguarino)\r\n\r\n## Contributing\r\n\r\nIssues and PRs welcome. Please open one if you encounter problems or have feature suggestions.\r\n\r\n## License\r\n\r\n[MIT License](./LICENSE)\r\n","readmeFilename":"README.md","_rev":"1-f79ffeaa14e2ced17c9672d45fb7f935"}