Supergateway (MCP Transport Gateway)
Author: supercorp-ai
Description: CLI gateway that bridges MCP stdio-based servers to network transports (SSE, WebSockets, Streamable HTTP) and can also connect to remote SSE/Streamable HTTP MCP servers and expose them locally over stdio. Useful for remote access, debugging, and using stdio-only MCP servers with web/remote clients.
Stars: 2.5k
Forks: 210
License: MIT License
Category: Open Source
Overview
Installation
### Option B: Run via Docker (official image)
1. Run the published image:```bash
docker run -it --rm -p 8000:8000 supercorp/supergateway \
--stdio "npx -y @modelcontextprotocol/server-filesystem /" \
--port 80002. Run:```bash
docker run -it --rm -p 8000:8000 supergateway --stdio "npx -y @modelcontextprotocol/server-filesystem ."2. Install deps, build, test:```bash
npm install
npm run build
npm testFAQs
How do I configure Supergateway to expose a Python-based MCP server using the uvx Docker variant?
Use the supercorp/supergateway:uvx image instead of the base image, then replace npx with uvx in your stdio command. For example: `docker run -p 8000:8000 supercorp/supergateway:uvx --stdio "uvx your-python-mcp-package" --outputTransport streamableHttp`. The uvx variant includes Python tooling preinstalled, eliminating the need to build a custom image with Python dependencies.
What are the security best practices for exposing an MCP server over the network with Supergateway in production?
Always deploy behind a reverse proxy like Nginx or Caddy that enforces TLS termination and rate limiting. Use `--oauth2Bearer` or `--header` flags to attach authentication tokens at the gateway layer, validating them in your proxy before traffic reaches Supergateway. Never expose Supergateway directly without authentication, firewall rules restricting source IPs, and monitoring for unauthorized access.
How does Supergateway handle multiple concurrent client connections to a single stdio MCP server?
Supergateway introduced concurrent handling in version 3.3 to enable shared stdio-backed deployments, allowing multiple network clients to connect simultaneously to a single gateway instance. Version 3.4 adjusted this for stability, indicating edge cases under certain workloads. Teams should test their specific usage patterns rather than assume unlimited concurrency, especially for high-throughput or stateful scenarios.
Can I use Supergateway with a reverse proxy like Nginx or an API gateway for enterprise-grade token validation and rate limiting?
Yes. Supergateway exposes standard HTTP endpoints on a configurable port, making it compatible with any reverse proxy or API gateway. Place Nginx, Traefik, Kong, or AWS API Gateway in front of the Supergateway endpoint to handle JWT validation, rate limiting, IP filtering, and TLS termination before requests reach the MCP server layer.
How can I optimize the performance of an MCP server?
Optimize MCP server performance with async operations for concurrent I/O, connection pooling to reduce overhead, and multi-level caching for repeated queries. Profile regularly to find bottlenecks, choose transport protocols by workload, and validate inputs with type-safe schemas. For cloud deployments, use provisioned concurrency to minimize cold starts and lazy-load resources on demand.
How do I troubleshoot connectivity issues on an MCP server?
Start by confirming network basics: stable internet and no firewall blocks. Check your client config file for typos in the MCP server URL, save changes, fully quit the application including background processes, then restart. Verify Node.js version eighteen or higher is installed, test connection by querying tool visibility, and review server logs for errors.