base on Run MCP stdio servers over SSE and SSE over stdio. AI gateway.  **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. Supported by [Supermachine](https://supermachine.ai) (hosted MCPs), [Superinterface](https://superinterface.ai), and [Supercorp](https://supercorp.ai). ## Installation & Usage Run Supergateway via `npx`: ```bash npx -y supergateway --stdio "uvx mcp-server-git" ``` - **`--stdio "command"`**: Command that runs an MCP server over stdio - **`--sse "https://mcp-server-ab71a6b2-cd55-49d0-adba-562bc85956e3.supermachine.app"`**: SSE URL to connect to (SSE→stdio mode) - **`--outputTransport stdio | sse | ws`**: Output MCP transport (default: `sse` with `--stdio`, `stdio` with `--sse`) - **`--port 8000`**: Port to listen on (stdio→SSE or stdio→WS mode, default: `8000`) - **`--baseUrl "http://localhost:8000"`**: Base URL for SSE or WS clients (stdio→SSE mode; optional) - **`--ssePath "/sse"`**: Path for SSE subscriptions (stdio→SSE mode, default: `/sse`) - **`--messagePath "/message"`**: Path for messages (stdio→SSE or stdio→WS mode, default: `/message`) - **`--header "x-user-id: 123"`**: Add one or more headers (stdio→SSE or SSE→stdio mode; can be used multiple times) - **`--oauth2Bearer "some-access-token"`**: Adds an `Authorization` header with the provided Bearer token - **`--logLevel info | none`**: Controls logging level (default: `info`). Use `none` to suppress all logs. - **`--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). - **`--healthEndpoint /healthz`**: Register one or more endpoints (stdio→SSE or stdio→WS mode; can be used multiple times) that respond with `"ok"` ## stdio → SSE Expose an MCP stdio server as an SSE server: ```bash npx -y supergateway \ --stdio "npx -y @modelcontextprotocol/server-filesystem ./my-folder" \ --port 8000 --baseUrl http://localhost:8000 \ --ssePath /sse --messagePath /message ``` - **Subscribe to events**: `GET http://localhost:8000/sse` - **Send messages**: `POST http://localhost:8000/message` ## SSE → stdio Connect to a remote SSE server and expose locally via stdio: ```bash npx -y supergateway --sse "https://mcp-server-ab71a6b2-cd55-49d0-adba-562bc85956e3.supermachine.app" ``` Useful for integrating remote SSE MCP servers into local command-line environments. You can also pass headers when sending requests. This is useful for authentication: ```bash npx -y supergateway \ --sse "https://mcp-server-ab71a6b2-cd55-49d0-adba-562bc85956e3.supermachine.app" \ --oauth2Bearer "some-access-token" \ --header "X-My-Header: another-header-value" ``` ## stdio → WS Expose an MCP stdio server as a WebSocket server: ```bash npx -y supergateway \ --stdio "npx -y @modelcontextprotocol/server-filesystem ./my-folder" \ --port 8000 --outputTransport ws --messagePath /message ``` - **WebSocket endpoint**: `ws://localhost:8000/message` ## Example with MCP Inspector (stdio → SSE mode) 1. **Run Supergateway**: ```bash npx -y supergateway --port 8000 \ --stdio "npx -y @modelcontextprotocol/server-filesystem /Users/MyName/Desktop" ``` 2. **Use MCP Inspector**: ```bash npx @modelcontextprotocol/inspector ``` You can now list tools, resources, or perform MCP actions via Supergateway. ## Using with ngrok Use [ngrok](https://ngrok.com/) to share your local MCP server publicly: ```bash npx -y supergateway --port 8000 --stdio "npx -y @modelcontextprotocol/server-filesystem ." # In another terminal: ngrok http 8000 ``` ngrok provides a public URL for remote access. MCP server will be available at URL similar to: https://1234-567-890-12-456.ngrok-free.app/sse ## Running with Docker A Docker-based workflow avoids local Node.js setup. A ready-to-run Docker image is available here: [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) ### Using the Official Image ```bash docker run -it --rm -p 8000:8000 supercorp/supergateway \ --stdio "npx -y @modelcontextprotocol/server-filesystem /" \ --port 8000 ``` Docker pulls the image automatically. The MCP server runs in the container’s root directory (`/`). You can mount host directories if needed. ### Building the Image Yourself Use provided Dockerfile: ```bash docker build -t supergateway . docker run -it --rm -p 8000:8000 supergateway \ --stdio "npx -y @modelcontextprotocol/server-filesystem /" \ --port 8000 ``` ## Using with Claude Desktop (SSE → stdio mode) Claude Desktop can use Supergateway’s SSE→stdio mode. ### NPX-based MCP Server Example ```json { "mcpServers": { "supermachineExampleNpx": { "command": "npx", "args": [ "-y", "supergateway", "--sse", "https://mcp-server-ab71a6b2-cd55-49d0-adba-562bc85956e3.supermachine.app" ] } } } ``` ### Docker-based MCP Server Example ```json { "mcpServers": { "supermachineExampleDocker": { "command": "docker", "args": [ "run", "-i", "--rm", "supercorp/supergateway", "--sse", "https://mcp-server-ab71a6b2-cd55-49d0-adba-562bc85956e3.supermachine.app" ] } } } ``` ## Using with Cursor (SSE → stdio mode) Cursor can also integrate with Supergateway in SSE→stdio mode. The configuration is similar to Claude Desktop. ### NPX-based MCP Server Example for Cursor ```json { "mcpServers": { "cursorExampleNpx": { "command": "npx", "args": [ "-y", "supergateway", "--sse", "https://mcp-server-ab71a6b2-cd55-49d0-adba-562bc85956e3.supermachine.app" ] } } } ``` ### Docker-based MCP Server Example for Cursor ```json { "mcpServers": { "cursorExampleDocker": { "command": "docker", "args": [ "run", "-i", "--rm", "supercorp/supergateway", "--sse", "https://mcp-server-ab71a6b2-cd55-49d0-adba-562bc85956e3.supermachine.app" ] } } } ``` **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. ## Why MCP? [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. ## Advanced Configuration Supergateway emphasizes modularity: - Automatically manages JSON-RPC versioning. - Retransmits package metadata where possible. - stdio→SSE or stdio→WS mode logs via standard output; SSE→stdio mode logs via stderr. ## Additional resources - [Superargs](https://github.com/supercorp-ai/superargs) - provide arguments to MCP servers during runtime. ## Contributors - [@StefanBurscher](https://github.com/StefanBurscher) - [@tarasyarema](https://github.com/tarasyarema) - [@pcnfernando](https://github.com/pcnfernando) - [@Areo-Joe](https://github.com/Areo-Joe) - [@Joffref](https://github.com/Joffref) - [@michaeljguarino](https://github.com/michaeljguarino) ## Contributing Issues and PRs welcome. Please open one if you encounter problems or have feature suggestions. ## License [MIT License](./LICENSE) ", Assign "at most 3 tags" to the expected json: {"id":"13247","tags":[]} "only from the tags list I provide: [{"id":77,"name":"3d"},{"id":89,"name":"agent"},{"id":17,"name":"ai"},{"id":54,"name":"algorithm"},{"id":24,"name":"api"},{"id":44,"name":"authentication"},{"id":3,"name":"aws"},{"id":27,"name":"backend"},{"id":60,"name":"benchmark"},{"id":72,"name":"best-practices"},{"id":39,"name":"bitcoin"},{"id":37,"name":"blockchain"},{"id":1,"name":"blog"},{"id":45,"name":"bundler"},{"id":58,"name":"cache"},{"id":21,"name":"chat"},{"id":49,"name":"cicd"},{"id":4,"name":"cli"},{"id":64,"name":"cloud-native"},{"id":48,"name":"cms"},{"id":61,"name":"compiler"},{"id":68,"name":"containerization"},{"id":92,"name":"crm"},{"id":34,"name":"data"},{"id":47,"name":"database"},{"id":8,"name":"declarative-gui "},{"id":9,"name":"deploy-tool"},{"id":53,"name":"desktop-app"},{"id":6,"name":"dev-exp-lib"},{"id":59,"name":"dev-tool"},{"id":13,"name":"ecommerce"},{"id":26,"name":"editor"},{"id":66,"name":"emulator"},{"id":62,"name":"filesystem"},{"id":80,"name":"finance"},{"id":15,"name":"firmware"},{"id":73,"name":"for-fun"},{"id":2,"name":"framework"},{"id":11,"name":"frontend"},{"id":22,"name":"game"},{"id":81,"name":"game-engine "},{"id":23,"name":"graphql"},{"id":84,"name":"gui"},{"id":91,"name":"http"},{"id":5,"name":"http-client"},{"id":51,"name":"iac"},{"id":30,"name":"ide"},{"id":78,"name":"iot"},{"id":40,"name":"json"},{"id":83,"name":"julian"},{"id":38,"name":"k8s"},{"id":31,"name":"language"},{"id":10,"name":"learning-resource"},{"id":33,"name":"lib"},{"id":41,"name":"linter"},{"id":28,"name":"lms"},{"id":16,"name":"logging"},{"id":76,"name":"low-code"},{"id":90,"name":"message-queue"},{"id":42,"name":"mobile-app"},{"id":18,"name":"monitoring"},{"id":36,"name":"networking"},{"id":7,"name":"node-version"},{"id":55,"name":"nosql"},{"id":57,"name":"observability"},{"id":46,"name":"orm"},{"id":52,"name":"os"},{"id":14,"name":"parser"},{"id":74,"name":"react"},{"id":82,"name":"real-time"},{"id":56,"name":"robot"},{"id":65,"name":"runtime"},{"id":32,"name":"sdk"},{"id":71,"name":"search"},{"id":63,"name":"secrets"},{"id":25,"name":"security"},{"id":85,"name":"server"},{"id":86,"name":"serverless"},{"id":70,"name":"storage"},{"id":75,"name":"system-design"},{"id":79,"name":"terminal"},{"id":29,"name":"testing"},{"id":12,"name":"ui"},{"id":50,"name":"ux"},{"id":88,"name":"video"},{"id":20,"name":"web-app"},{"id":35,"name":"web-server"},{"id":43,"name":"webassembly"},{"id":69,"name":"workflow"},{"id":87,"name":"yaml"}]" returns me the "expected json"