Supergateway

https://github.com/supercorp-ai/supergateway
Admin
Supergateway runs MCP stdio-based servers over SSE, WebSockets, or Streamable HTTP, enabling remote...
Tokens:98,425
Snippets:636
Trust Score:9.3
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install Node 24 and run the test suite

Source: https://github.com/supercorp-ai/supergateway/blob/main/README.md

Use nvm to install and activate Node 24, then install dependencies, build, and run the test suite. Requires Node 24+ and uses the local mock MCP server for offline tests.

```bash
nvm install 24
nvm use 24
npm install
npm run build
npm test
```

--------------------------------

### Install Node.js v24 and dependencies

Source: https://github.com/supercorp-ai/supergateway/blob/main/AGENTS.md

Use nvm to install and use Node.js v24, then install npm dependencies. Run these commands after checking out the repository.

```bash
nvm install 24
nvm use 24
npm install
```

--------------------------------

### Start a gateway programmatically with stdio input and SSE output

Source: https://github.com/supercorp-ai/supergateway/blob/main/_autodocs/api-reference/start-and-server-options.md

Imports CLI parsing and start utilities, parses CLI arguments for a stdio server on port 8000 with SSE output, and starts the gateway. Logs 'Listening on port 8000' and 'SSE endpoint: http://localhost:8000/sse'.

```TypeScript
import { parseCli, inputTransportOf, hostOf } from './cli.js'
import { start } from './startOne.js'
import { keyedServers, invocation } from './invocation.js'
import { getLogger } from './lib/getLogger.js'
import { orExit } from './exits.js'

const cli = parseCli([
  '--stdio', 'uvx mcp-server-git',
  '--port', '8000',
  '--outputTransport', 'sse',
])
const logger = getLogger({ logLevel: 'info', outputTransport: 'sse' })
const run = invocation([], cli, logger) // no --config
const argv = 'argv' in run ? run.argv : run.servers[0].argv
const { input } = orExit(logger, inputTransportOf(argv))
const { host } = orExit(logger, hostOf(argv))
const servers = keyedServers(run, argv, logger, () => logger)

await start(input, argv, logger, { host, apiKeys: servers[0].apiKeys })
// → "Listening on port 8000", "SSE endpoint: http://localhost:8000/sse"
```

--------------------------------

### start method signature

Source: https://github.com/supercorp-ai/supergateway/blob/main/_autodocs/api-reference/gateway-stdio-to-ws.md

Declares the start method that waits for connection events, assigns client IDs, and installs message, close, and error handlers.

```typescript
start(): void
```

--------------------------------

### supergateway config: combine multiple MCP servers under one entry

Source: https://github.com/supercorp-ai/supergateway/blob/main/README.md

Configure a supergateway entry with its own mcpServers to serve multiple MCP servers as one MCP server at the entry's URL. The example combines git, files, and docs servers under the 'dev' entry. Names are not changed; the first server with a duplicate name wins. Each session starts its own servers, and a server that fails to start is left out. Settings like outputTransport and apiKey go on the entry. Combining goes one level deep.

```jsonc
{
  "port": 8000,
  "outputTransport": "streamableHttp",
  "mcpServers": {
    "dev": {
      "mcpServers": {
        "git": { "command": "uvx", "args": ["mcp-server-git"] },
        "files": {
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-filesystem", "."],
        },
        "docs": {
          "url": "https://docs.example.com/mcp",
          "type": "http",
          "toolPrefix": "docs_",
        },
      },
    },
  },
}
```

--------------------------------

### Start Supergateway with --config

Source: https://github.com/supercorp-ai/supergateway/blob/main/README.md

Command to start Supergateway using a config file. The file is read as the mcpServers file used by Claude Desktop and other MCP clients.

```bash
npx -y supergateway --config servers.json
```

--------------------------------

### Modern request flow example

Source: https://github.com/supercorp-ai/supergateway/blob/main/_autodocs/api-reference/modern-http-relay.md

Shows how to set up the modern relay in a Streamable HTTP gateway, including mounting before legacy routes, handling shutdown, and an example modern POST request with headers and body.

```typescript
import { createModernHttp, modernRelayFor } from './lib/modernHttp.js'
import { MODERN_VERSION } from './lib/modernVersion.js'

// Mounted before the legacy routes in both Streamable HTTP gateways:
const relay = modernRelayFor(source, children, logger)
app.post(streamableHttpPath, async (req, res) => {
  if (children.closing) { res.status(503).send('Gateway is shutting down'); return }
  if (await relay?.handle(req, res)) return   // served (or rejected): done
  /* ...legacy stateless/stateful path... */
})
await relay?.close() // at gateway shutdown

// A modern POST:
//   POST /mcp
//   mcp-protocol-version: 2026-07-28
//   mcp-method: tools/call
//   mcp-name: search
//   mcp-param-query: "mcp"
//   body: {"jsonrpc":"2.0","id":1,"method":"tools/call",
//          "params":{"name":"search","arguments":{"query":"mcp"}}}
```

--------------------------------

### stdioToSse: Serve a stdio server over SSE

Source: https://github.com/supercorp-ai/supergateway/blob/main/_autodocs/api-reference/gateway-stdio-to-sse.md

Starts an SSE gateway that spawns the given stdio command and exposes it via SSE endpoints. Configure the port, base URL, SSE and message paths, CORS, health endpoints, headers, and API keys. Clients connect to GET /sse and then POST to /message with the session ID.

```typescript
import { stdioToSse, type StdioToSseMountArgs } from './gateways/stdioToSse.js'
import { getLogger } from './lib/getLogger.js'

await stdioToSse({
  stdioCmd: 'uvx mcp-server-git', // ServerSource: a --stdio command
  port: 8000,
  baseUrl: 'http://localhost:8000',
  ssePath: '/sse',
  messagePath: '/message',
  logger: getLogger({ logLevel: 'info', outputTransport: 'sse' }),
  corsOrigin: '*',
  healthEndpoints: ['/healthz'],
  headers: { 'X-Gateway': 'supergateway' },
  apiKeys: ['secret-key'],
})
// Clients: GET http://localhost:8000/sse, then POST /message?sessionId=...
```

--------------------------------

### Driving the invocation directly

Source: https://github.com/supercorp-ai/supergateway/blob/main/_autodocs/api-reference/invocation-and-exits.md

Example showing how to parse CLI arguments, create a logger, build an invocation, and call announceStart. The comment shows the expected output lines.

```typescript
import { parseCli, givenOptions } from './cli.js'
import { invocation, keyedServers, announceStart } from './invocation.js'
import { getLogger } from './lib/getLogger.js'
import { inputTransportOf, hostOf, exitWithProcessOf } from './cli.js'
import { orExit } from './exits.js'

const cli = parseCli(['--config', 'servers.json'])
const logger = getLogger({ logLevel: 'info', outputTransport: 'sse' })
const run = invocation(['--config', 'servers.json'], cli, logger)
const argv = 'argv' in run ? run.argv : run.servers[0].argv
const servers = keyedServers(run, argv, logger, (name) => logger)
announceStart(logger, run, argv, undefined, undefined)
// → Starting... / outputTransport: … or the multi-server port listing
```

--------------------------------

### Install Supergateway via Homebrew

Source: https://github.com/supercorp-ai/supergateway/blob/main/README.md

Installs Supergateway on macOS and Linux using Homebrew. Requires Homebrew to be installed.

```bash
brew install supercorp-ai/tap/supergateway
```

--------------------------------

### stdioToSse

Source: https://github.com/supercorp-ai/supergateway/blob/main/_autodocs/api-reference/gateway-stdio-to-sse.md

Starts an HTTP server that serves a stdio-based MCP server over SSE. Clients connect via GET to the SSE endpoint and send messages via POST to the message endpoint.

```APIDOC
## stdioToSse

### Description
Starts an HTTP server that bridges a stdio command to SSE clients. Clients connect to the SSE endpoint and send JSON-RPC messages via the message endpoint.

### Method
N/A (function call)

### Endpoint
N/A

### Parameters
#### Function Arguments
- **stdioCmd** (string) - Required - The command to start the stdio server (e.g., 'uvx mcp-server-git').
- **port** (number) - Required - The port to listen on.
- **baseUrl** (string) - Required - The base URL of the server (e.g., 'http://localhost:8000').
- **ssePath** (string) - Required - The path for the SSE endpoint (e.g., '/sse').
- **messagePath** (string) - Required - The path for the message endpoint (e.g., '/message').
- **logger** (object) - Required - A logger instance (e.g., from getLogger).
- **corsOrigin** (string) - Optional - CORS origin setting (e.g., '*').
- **healthEndpoints** (string[]) - Optional - Array of health check endpoint paths (e.g., ['/healthz']).
- **headers** (object) - Optional - Additional HTTP headers to set on responses (e.g., { 'X-Gateway': 'supergateway' }).
- **apiKeys** (string[]) - Optional - Array of API keys for authentication (e.g., ['secret-key']).

### Request Example
```ts
await stdioToSse({
  stdioCmd: 'uvx mcp-server-git',
  port: 8000,
  baseUrl: 'http://localhost:8000',
  ssePath: '/sse',
  messagePath: '/message',
  logger: getLogger({ logLevel: 'info', outputTransport: 'sse' }),
  corsOrigin: '*',
  healthEndpoints: ['/healthz'],
  headers: { 'X-Gateway': 'supergateway' },
  apiKeys: ['secret-key'],
})
```

### Response
#### Success Response
- Starts the server and begins listening on the specified port.

#### Client Interaction
- **GET** `http://localhost:8000/sse` - Establishes an SSE connection.
- **POST** `http://localhost:8000/message?sessionId=...` - Sends a message to the server.

### Error Handling
- **400** - "Missing sessionId parameter" - Returned when a client POSTs without a sessionId.
- **503** - "No active SSE connection for session <id>" - Returned when a POST is made for an unknown or closed session.
- **-32603** - "MCP server process failed" - Returned per-request when the child process fails with calls in flight.
```

--------------------------------

### startServer function implementation

Source: https://github.com/supercorp-ai/supergateway/blob/main/_autodocs/api-reference/children-and-server-source.md

Starts a server peer for a given source, wrapping it with toolNamesPeer if toolNames is set. The spawn parameter is the gateway's own, which tests replace.

```TypeScript
export function startServer(
  spawn: Spawn,
  source: ServerSource,
  children: OwnedChildProcesses,
  logger: Logger,
  label: string,
): StartPeer {
  const start = serverPeer(spawn, source, children, logger, label)
  return source.toolNames ? toolNamesPeer(start, source.toolNames) : start
}

```

--------------------------------

### Require API key for stdio to Streamable HTTP with curl example

Source: https://github.com/supercorp-ai/supergateway/blob/main/README.md

Use this command to require an API key for all requests when serving a stdio-based MCP server over Streamable HTTP. The curl example shows how to send the key via Authorization header or X-API-Key header. Requests without a valid key get 401 Unauthorized. Health endpoint paths and browser preflight requests (with --cors) remain open. Keys from --apiKey, --apiKeyFile, SUPERGATEWAY_API_KEY, and SUPERGATEWAY_API_KEY_FILE are all accepted together. An empty key, unreadable key file, or file with no keys stops the gateway at startup. Keys are never logged; use HTTPS to avoid sending them in clear text.

```bash
npx -y supergateway \
    --stdio "npx -y @modelcontextprotocol/server-filesystem ./my-folder" \
    --outputTransport streamableHttp --apiKey "$MCP_API_KEY"
```

```bash
curl -H "Authorization: Bearer $MCP_API_KEY" ...   # or: -H "X-API-Key: $MCP_API_KEY"
```

--------------------------------

### CLI entry point usage example

Source: https://github.com/supercorp-ai/supergateway/blob/main/_autodocs/api-reference/cli.md

Shows how the CLI layer is exercised in src/index.ts: parses arguments, logs warnings, and extracts input transport and host.

```TypeScript
import { hideBin } from 'yargs/helpers'
import { parseCli, unknownArguments, inputTransportOf, hostOf } from './cli.js'
import { getLogger } from './lib/getLogger.js'
import { orExit } from './exits.js'

const args = hideBin(process.argv)
const cli = parseCli(args)
const cliLogger = getLogger({
  logLevel: cli.logLevel,
  logFormat: cli.logFormat,
  outputTransport: cli.outputTransport as string,
})
for (const warning of unknownArguments(args, cli)) cliLogger.error(warning)
const { input } = orExit(cliLogger, inputTransportOf(cli))
const { host } = orExit(cliLogger, hostOf(cli))
```

--------------------------------

### start function - src/startOne.ts:63

Source: https://github.com/supercorp-ai/supergateway/blob/main/_autodocs/api-reference/start-and-server-options.md

Starts a server based on the output transport. For non-stdio outputs, it listens; for stdio output with local input and no combined entry, it errors; otherwise it calls onStdio.

```typescript
export async function start(
  input: InputTransport,
  argv: Cli,
  logger: Logger,
  listening: Listening,
) {
  if (argv.outputTransport !== 'stdio') await listen(argv, logger, listening)
  else if (input === 'stdio' && !argv.combined)
    unsupported(logger, input, argv.outputTransport)
  else await onStdio(input, argv, logger)
}
```

--------------------------------

### stdioToStatefulStreamableHttpMount(args)

Source: https://github.com/supercorp-ai/supergateway/blob/main/_autodocs/api-reference/gateway-streamable-http.md

Creates the mount configuration for the stateful Streamable HTTP gateway, defining POST, GET, and DELETE routes for session management.

```APIDOC
## `stdioToStatefulStreamableHttpMount(args): Mount`

### Description
Returns a mount object that defines the HTTP routes for the stateful Streamable HTTP gateway. The routes are all on `streamableHttpPath` and handle POST, GET, and DELETE methods for session management.

### Method
POST, GET, DELETE

### Endpoint
`streamableHttpPath` (the path is provided in the mount configuration)

### Parameters
#### Path Parameters
- **streamableHttpPath** (string) - Required - The base path for all Streamable HTTP routes.

### Request Example
N/A

### Response
#### Success Response
- **Mount** - An object containing the routes and the shared Express app.

#### Response Example
N/A
```

--------------------------------

### upstreamLost and rejectMalformedInitialize

Source: https://github.com/supercorp-ai/supergateway/blob/main/_autodocs/api-reference/upstream-connections.md

Example showing how to use upstreamLost to detect upstream connection failures and rejectMalformedInitialize to validate initialize parameters before sending upstream.

```APIDOC
## upstreamLost(err)

### Description
Checks whether a given error indicates that the upstream connection or session is lost. Returns true for errors such as HTTP 404 (session expired), HTTP 5xx, or 'fetch failed'.

### Parameters
- **err** (Error) - Required - The error object caught from a request.

### Returns
- **boolean** - True if the upstream is lost, false otherwise.

## rejectMalformedInitialize(params)

### Description
Validates that the initialize request parameters are well-formed. Throws an error with code -32602 (InvalidParams) and message 'Invalid initialize parameters' if the parameters are malformed.

### Parameters
- **params** (object) - Required - The initialize request parameters to validate.

### Throws
- **Error** - With code -32602 and message 'Invalid initialize parameters' if validation fails.

### Example
```ts
import { upstreamLost, rejectMalformedInitialize } from './gateways/upstreamFailures.js'

try {
  await client.request(req, z.any(), { signal, timeout: 300_000 })
} catch (err) {
  if (upstreamLost(err)) {
    // The session/connection is gone: reconnect before the next request.
    // A 404 (session expired), HTTP 5xx, or "fetch failed" all match.
  } else {
    // Answer the stdio client with errorResponse(req, err).
  }
}

// Malformed initialize params are refused before anything is sent upstream:
try {
  rejectMalformedInitialize({ jsonrpc: '2.0', id: 1, method: 'initialize', params: { nope: 1 } })
} catch (err) {
  // err.code === -32602 (ErrorCode.InvalidParams), message 'Invalid initialize parameters'
}
```
```

--------------------------------

### stdioToWs(args: StdioToWsArgs): Promise<void>

Source: https://github.com/supercorp-ai/supergateway/blob/main/_autodocs/api-reference/gateway-stdio-to-ws.md

Starts the stdio→WS gateway on the specified port, creating a WebSocket server that spawns a child process per connection and passes messages through unchanged.

```APIDOC
## stdioToWs(args: StdioToWsArgs): Promise<void>

### Description
Starts the stdio→WS gateway on the specified port, creating a WebSocket server that spawns a child process per connection and passes messages through unchanged.

### Method
Function

### Signature
```ts
export async function stdioToWs(args: StdioToWsArgs): Promise<void>
```

### Parameters
#### Args (StdioToWsArgs)
- **port** (number) - Required - Port to listen on.
- **host** (string | undefined) - Optional - Address to listen on. Defaults to every interface.
- **messagePath** (string) - Required - WebSocket endpoint path. Defaults to '/message'.
- **logger** (Logger) - Required - Log sink.
- **corsOrigin** (CorsOptions['origin']) - Required - CORS policy for plain-HTTP requests. Defaults to false.
- **healthEndpoints** (string[]) - Required - Paths answering "ok". Defaults to [].
- **healthCheck** (HealthCheck) - Optional - What health endpoints check. Defaults to 'gateway'.
- **apiKeys** (string[]) - Optional - Keys a client must present. Defaults to [].

### Returns
Promise<void> - Resolves when the gateway is started.

### Example
```ts
import { stdioToWs } from './gateways/stdioToWs'

await stdioToWs({
  port: 8080,
  messagePath: '/message',
  logger: console,
  corsOrigin: false,
  healthEndpoints: ['/health'],
})
```
```

--------------------------------

### stdioToWs function implementation

Source: https://github.com/supercorp-ai/supergateway/blob/main/_autodocs/api-reference/gateway-stdio-to-ws.md

Starts the gateway alone on the port. Unlike the SSE variant, this needs an http.createServer because HTTP upgrades must be captured and handed to the WebSocket transport.

```typescript
export async function stdioToWs(args: StdioToWsArgs) {
  const { port, host, logger } = args
  const mount = stdioToWsMount(args)
  // @types/express declares RequestHandler as returning `void | Promise<void>`...
  const httpServer = keepConnectionsAlive(createServer(mount.app))
  httpServer.on('upgrade', mount.upgrade.handle)
  onSignals({ logger, cleanup: mount.close, drainStdin: true })
  listenOn(httpServer, port, host, () => {
    logger.info(`Listening on port ${port}`)
    mount.listening(host, port)
  })
}
```

--------------------------------

### stdioToSse(args: StdioToSseArgs): Promise<void>

Source: https://github.com/supercorp-ai/supergateway/blob/main/_autodocs/api-reference/gateway-stdio-to-sse.md

Starts the gateway alone on the port: builds the mount, registers signal cleanup, bumps keep-alive timeouts, and listens. This is the function used for a single-server command line.

```APIDOC
## stdioToSse(args: StdioToSseArgs): Promise<void>

### Description
Starts the gateway alone on the port: builds the mount, registers signal cleanup (stopping the children), bumps keep-alive timeouts, and listens. This is the function used for a single-server command line.

### Signature
```ts
export async function stdioToSse(args: StdioToSseArgs): Promise<void>
```

### Parameters
- **args** (StdioToSseArgs) - Required - The arguments for starting the gateway.

### StdioToSseArgs Type
```ts
export type StdioToSseArgs = ServerSource & StdioToSseOptions
```

### StdioToSseOptions (not exported)
```ts
interface StdioToSseOptions {
  port: number
  host?: string
  baseUrl: string
  ssePath: string
  messagePath: string
  logger: Logger
  corsOrigin: CorsOptions['origin']
  healthEndpoints: string[]
  healthCheck?: HealthCheck
  headers: Record<string, string>
  apiKeys?: string[]
}
```

### Options Table
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `port` | `number` | yes | — | Port to listen on |
| `host` | `string \| undefined` | no | every interface | Address to listen on |
| `baseUrl` | `string` | yes | `''` | Base URL prefix for the message endpoint |
| `ssePath` | `string` | yes | `'/sse'` | Path for SSE subscriptions |
| `messagePath` | `string` | yes | `'/message'` | Path for message POSTs |
| `logger` | `Logger` | yes | — | Log sink |
| `corsOrigin` | `CorsOptions['origin']` | yes | `false` | CORS origin policy |
| `healthEndpoints` | `string[]` | yes | `[]` | Paths answering `"ok"` |
| `healthCheck` | `HealthCheck` | no | `'gateway'` | What health endpoints check |
| `headers` | `Record<string, string>` | yes | — | `--header` response headers |
| `apiKeys` | `string[]` | no | `[]` | Keys a client must present |

### Returns
- `Promise<void>` - Resolves when the gateway is started.
```

--------------------------------

### serve() with mounts and health endpoint

Source: https://github.com/supercorp-ai/supergateway/blob/main/_autodocs/api-reference/serve-health-and-listening.md

Sets up an HTTP server on a single port serving multiple MCP mounts (e.g., SSE gateway) and a shared health endpoint. It checks for route conflicts before starting the server.

```APIDOC
## serve(port, host, logger, mounts, healthEndpoints)

### Description
Starts an HTTP server that serves multiple MCP mounts on a single port, along with a shared health endpoint. The server listens on the specified port and host, and routes requests to the appropriate mount based on path.

### Method
N/A (function call)

### Endpoint
N/A (function call)

### Parameters
- **port** (number) - Required - The port number to listen on.
- **host** (string | undefined) - Optional - The hostname or IP address to bind to. If undefined, binds to all interfaces.
- **logger** (Logger) - Required - Logger instance for logging.
- **mounts** (Array<Mount>) - Required - Array of mount objects, each defining a path and routes.
- **healthEndpoints** (Array<string>) - Optional - Array of paths that serve health check responses.

### Request Example
ts
serve({ port: 8000, host: undefined, logger, mounts, healthEndpoints: ['/healthz'] })


### Response
#### Success Response
- **GET /healthz** - Returns "ok" when the server is healthy.
- **GET /git/sse** - Returns the SSE stream for the git mount.
- **GET /other** - Returns Express 404 for unknown routes.

#### Response Example

GET /healthz → "ok"
GET /git/sse  → SSE stream
GET /other    → 404


### Error Handling
- If a route conflict is detected, the server does not start and an error is logged.

```

--------------------------------

### toolNamesPeer(start, names)

Source: https://github.com/supercorp-ai/supergateway/blob/main/_autodocs/api-reference/tools-and-security.md

Creates a server that filters tools based on the provided names. It intercepts tool calls and list requests, and handles JSON-RPC batches.

```APIDOC
## toolNamesPeer(start, names)

### Description
Creates a server whose tools a client sees through `names`. It answers calls to tools the client can't see, rewrites `tools/list` results, and parses JSON-RPC batches message by message.

### Parameters
- **start** (StartPeer) - Required - The underlying server to wrap.
- **names** (ToolNames) - Required - The set of tool names to expose.

### Returns
- **StartPeer** - The wrapped server with filtered tool visibility.
```

--------------------------------

### stdioToStatefulStreamableHttp(args)

Source: https://github.com/supercorp-ai/supergateway/blob/main/_autodocs/api-reference/gateway-streamable-http.md

Function that starts a stateful Streamable HTTP gateway from a stdio-based MCP server, announcing the session timeout.

```APIDOC
## `stdioToStatefulStreamableHttp(args: StdioToStreamableHttpArgs): Promise<void>`

### Description
Starts a stateful Streamable HTTP gateway that bridges a stdio-based MCP server to HTTP. It announces the session timeout in the server information (either `Session timeout: <ms>` or `disabled`).

### Method
N/A (function call)

### Endpoint
N/A

### Parameters
#### Function Parameters
- **args** (`StdioToStreamableHttpArgs`) - Required - The arguments for the gateway, same shape as the stateless variant, but with `sessionTimeout: number | null` instead of `protocolVersion`.

### Request Example
N/A

### Response
#### Success Response
- **Promise<void>** - Resolves when the gateway is started.

#### Response Example
N/A
```

--------------------------------

### GET {ssePath}

Source: https://github.com/supercorp-ai/supergateway/blob/main/_autodocs/endpoints.md

Establishes a Server-Sent Events (SSE) subscription stream for receiving server-to-client events.

```APIDOC
## GET {ssePath}

### Description
Establishes a Server-Sent Events (SSE) subscription stream for receiving server-to-client events.

### Method
GET

### Endpoint
{ssePath}

### Response
#### Success Response (200)
- **body** (stream) - SSE event stream.

#### Response Example
No explicit example provided.
```

--------------------------------

### Run supergateway in stateless Streamable HTTP mode

Source: https://github.com/supercorp-ai/supergateway/blob/main/README.md

Starts a Streamable HTTP server in stateless mode. The endpoint defaults to http://localhost:8000/mcp (configurable via --streamableHttpPath).

```bash
npx -y supergateway \
    --stdio "npx -y @modelcontextprotocol/server-filesystem ./my-folder" \
    --outputTransport streamableHttp \
    --port 8000
```

--------------------------------

### combinedToStdio(args: CombinedToStdioArgs)

Source: https://github.com/supercorp-ai/supergateway/blob/main/_autodocs/api-reference/bridges-to-stdio.md

Combines multiple MCP servers into a single stdio process. It starts the member servers when the client initializes and routes messages between the client and the servers.

```APIDOC
## combinedToStdio(args: CombinedToStdioArgs)

### Description
Combines multiple MCP servers into a single stdio process. It starts the member servers when the client initializes and routes messages between the client and the servers.

### Method
Function

### Signature
```ts
export function combinedToStdio(args: CombinedToStdioArgs)
```

### Parameters
#### Args
- **logger** (Logger) - Required - Logger instance for logging.
- **lifecycle** (BridgeLifecycle) - Optional - Lifecycle callbacks for signal handling and exit. Defaults to registering signal handlers and exiting with process.exit.
- **serverSource** (ServerSource) - Required - Configuration for the member servers to combine.

### Behavior
- The process is one session; member servers start when the client initializes.
- Invalid JSON on stdin is logged and the session continues.
- Servers are read no faster than the client reads stdout (drained([process.stdout])).

```

--------------------------------

### Run Supergateway with MCP Inspector (stdio to SSE)

Source: https://github.com/supercorp-ai/supergateway/blob/main/README.md

Start Supergateway on port 8000, bridging stdio to SSE, then launch MCP Inspector to interact with the MCP server.

```bash
npx -y supergateway --port 8000 \
    --stdio "npx -y @modelcontextprotocol/server-filesystem /Users/MyName/Desktop"
```

```bash
npx @modelcontextprotocol/inspector
```

--------------------------------

### stdioToSse function

Source: https://github.com/supercorp-ai/supergateway/blob/main/_autodocs/api-reference/gateway-stdio-to-sse.md

Starts the gateway alone on the port: builds the mount, registers signal cleanup, bumps keep-alive timeouts, and listens. Used for a single-server command line.

```typescript
export async function stdioToSse(args: StdioToSseArgs) {
  const { port, host, logger } = args
  const mount = stdioToSseMount(args)
  onSignals({ logger, cleanup: mount.close, drainStdin: true })
  keepConnectionsAlive(
    listenOn(mount.app, port, host, () => {
      logger.info(`Listening on port ${port}`)
      mount.listening(host, port)
    }),
  )
}
```

--------------------------------

### sseToStdio(args: SseToStdioArgs): Promise<void>

Source: https://github.com/supercorp-ai/supergateway/blob/main/_autodocs/api-reference/bridges-to-stdio.md

Starts a bridge that connects an SSE-based MCP server to a stdio client. It creates an upstream client, a stdio server, and relays messages between them.

```APIDOC
## sseToStdio(args: SseToStdioArgs): Promise<void>

### Description
Starts a bridge that connects an SSE-based MCP server to a stdio client. It creates an upstream client, a stdio server, and relays messages between them.

### Method
Function call

### Signature
```ts
export async function sseToStdio(args: SseToStdioArgs): Promise<void>
```

### Parameters
#### args (SseToStdioArgs) - Required
- **sseUrl** (string) - Required - The URL of the SSE server to connect to.
- **logger** (Logger) - Required - Logger instance for logging.
- **headers** (Record<string, string>) - Required - HTTP headers to send with the SSE connection.
- **lifecycle** (BridgeLifecycle) - Optional - Lifecycle callbacks. Defaults to registering signal handlers and exiting the process.
- **toolNames** (ToolNames) - Optional - The tools the stdio client sees of the server, if not all as they are.

### Behavior
- On handshake timeout, the bridge closes the SSE transport after notifying the client, as the SDK transport cannot be restarted.

### Returns
Promise<void> - Resolves when the bridge is set up and running.
```

--------------------------------

### stdioToStatefulStreamableHttp

Source: https://github.com/supercorp-ai/supergateway/blob/main/_autodocs/api-reference/gateway-streamable-http.md

Starts a stateful Streamable HTTP gateway that maintains sessions. Sessions are created with an initialize request and destroyed with a DELETE request. Supports SSE streams for server notifications.

```APIDOC
## stdioToStatefulStreamableHttp

### Description
Starts a stateful Streamable HTTP gateway that maintains sessions. Sessions are created with an initialize request and destroyed with a DELETE request. Supports SSE streams for server notifications.

### Methods
POST, GET, DELETE

### Endpoint
/mcp

### Parameters
#### Request Body (POST)
- **JSON-RPC body** (object) - Required - The JSON-RPC request to send to the MCP server.

#### Headers
- **Mcp-Session-Id** (string) - Required for subsequent requests - Session identifier returned from initialize.

### Request Example (Initialize)
```json
{
  "jsonrpc": "2.0",
  "method": "initialize",
  "params": {},
  "id": 1
}
```

### Response
#### Success Response (200)
- **result** (object) - The JSON-RPC response from the MCP server.
- **Mcp-Session-Id** (string) - Session identifier header.

#### Response Example
```json
{
  "jsonrpc": "2.0",
  "result": {},
  "id": 1
}
```

### Additional Operations
- **POST /mcp with Mcp-Session-Id** - Routes to that session's child process.
- **GET /mcp with Mcp-Session-Id** - Returns SSE stream of server notifications.
- **DELETE /mcp with Mcp-Session-Id** - Terminates the session; further POSTs return 404.

### Configuration Options
- **stdioCmd** (string) - Required - Command to spawn the child process.
- **port** (number) - Required - Port to listen on.
- **streamableHttpPath** (string) - Required - Path for the Streamable HTTP endpoint.
- **logger** (object) - Required - Logger instance.
- **corsOrigin** (boolean|string) - Optional - CORS origin setting.
- **healthEndpoints** (array) - Optional - Health check endpoints.
- **headers** (object) - Optional - Additional headers.
- **apiKeys** (array) - Optional - API keys for authentication.
- **sessionTimeout** (number) - Optional - Session timeout in milliseconds.
```

--------------------------------

### Example --config file (JSONC) showing gateway settings and mcpServers entries

Source: https://github.com/supercorp-ai/supergateway/blob/main/_autodocs/configuration.md

Shows the shape of the --config file: gateway-wide settings (port, host, logLevel, logFormat, exitWithProcess, healthEndpoint), top-level endpoint defaults (outputTransport, apiKey), and an mcpServers map with one entry. The entry uses command/args, env, cwd, per-entry overrides, and disabled. Comments and trailing commas are allowed (JSONC).

```jsonc
{
  // Gateway-wide settings (the file's own flags):
  "port": 8000,
  "host": "127.0.0.1",
  "logLevel": "info",
  "logFormat": "text",
  "exitWithProcess": 1234,
  "healthEndpoint": ["/healthz"],

  // Top-level endpoint options: defaults for every entry:
  "outputTransport": "streamableHttp",
  "apiKey": ["k1"],

  "mcpServers": {            // required; at least one enabled server
    "<name>": {              // served at /<name>, or at its "path"
      "command": "uvx", "args": ["mcp-server-git"],   // one of command/stdio/url
      "env": { "KEY": "value" }, "cwd": "/tmp",        // local-server extras
      "option": "any flag by its name",                // per-entry overrides
      "disabled": false,                                // skip this entry
    }
  }
}
```

--------------------------------

### StatefulSessions.request method

Source: https://github.com/supercorp-ai/supergateway/blob/main/_autodocs/api-reference/stateful-sessions-and-stateless-requests.md

Handles a GET or DELETE request for a session. Requires a session ID; returns 400 if missing, 404 if unknown. For GET, starts the session's liveness probe if present, stopped when the response finishes.

```typescript
async request(req: express.Request, res: express.Response) {
  const sessionId = req.headers['mcp-session-id'] as string | undefined
  if (!sessionId) {
    res.status(400).send('Invalid or missing session ID')
    return
  }
  if (!this.transports.has(sessionId)) {
    // Unknown session id -> 404 so the client re-initializes instead of
    // retrying a dead id.
    res.status(404).send('Session not found')
    return
  }
  // ...counter, GET liveness probe start/stop, countResponse, watch, then:
  await transport.handleRequest(req, res)
}
```

--------------------------------

### mountFor function signature (src/lib/serve.ts:38)

Source: https://github.com/supercorp-ai/supergateway/blob/main/_autodocs/api-reference/serve-health-and-listening.md

Finds the mount a request belongs to: the one with the longest path the request's path starts with, segment by segment. For example, `/git` takes `/git/sse` but not `/github/sse`.

```TypeScript
export function mountFor<M extends Pick<Mount, 'path'>>(
  mounts: M[],
  path: string,
): M | undefined
```

--------------------------------

### Stateful session lifecycle with stdioToStatefulStreamableHttp

Source: https://github.com/supercorp-ai/supergateway/blob/main/_autodocs/api-reference/stateful-sessions-and-stateless-requests.md

Example of setting up a stateful streamable HTTP gateway. Shows initialization, session reuse, timeout cleanup, and re-initialization after session not found. Includes expected HTTP responses and JSON-RPC error codes.

```typescript
import { stdioToStatefulStreamableHttp } from './gateways/stdioToStatefulStreamableHttp.js'

await stdioToStatefulStreamableHttp({
  stdioCmd: 'uvx mcp-server-git',
  port: 8000,
  streamableHttpPath: '/mcp',
  logger,
  corsOrigin: false,
  healthEndpoints: [],
  headers: {},
  apiKeys: [],
  sessionTimeout: 60_000,
})
// 1. POST /mcp { initialize }         → 200, Mcp-Session-Id header issued,
//                                       a child starts for the session
// 2. POST /mcp + Mcp-Session-Id       → same child answers
// 3. 60s of no activity               → "Session <id> timed out, cleaning up";
//                                       the transport closes, the child stops
// 4. POST /mcp + that session id      → 404 JSON-RPC -32001 "Session not found",
//                                       so a compliant client re-initializes
```

--------------------------------

### serve({ port, host, logger, mounts, healthEndpoints, stdio }): Server

Source: https://github.com/supercorp-ai/supergateway/blob/main/_autodocs/api-reference/serve-health-and-listening.md

Starts the gateway HTTP server, listening on the given port for several mounted servers. It owns the gateway's shutdown, keep-alive, and health endpoints, and routes requests to the appropriate mount.

```APIDOC
## `serve({ port, host, logger, mounts, healthEndpoints, stdio }): Server`

### Description
Starts the gateway HTTP server, listening on the given port for several mounted servers. It owns the gateway's shutdown, keep-alive, and health endpoints, and routes requests to the appropriate mount.

### Parameters
- **port** (number) - Required - The port to listen on.
- **host** (string | undefined) - Optional - The host to bind to.
- **logger** (Logger) - Required - Logger instance.
- **mounts** (Mount[]) - Required - Array of mounted servers.
- **healthEndpoints** (string[]) - Required - The gateway's own health endpoints.
- **stdio** ({ close: () => Promise<void> } | undefined) - Optional - The entry served on stdio beside the mounts; it reads stdin itself, so the gateway leaves stdin to it.

### Returns
- **Server** - The created server instance.

### Behavior
- One Express app (`shared`) answers the health endpoints and sends every other request to its mount via `mountFor`; a request no mount takes gets Express's 404.
- When any mount has an `upgrade`, the HTTP server is created with `createServer(handler)` and an `'upgrade'` listener routes each upgrade to the mount whose `upgrade.path` matches (or, for an upgrade with no matching path, to the first socket mount, which refuses it the way a WebSocket server alone on the port always has).
- `onSignals` runs every mount's `close()` and the stdio entry's close at shutdown; `drainStdin` is disabled when a stdio entry is present (it reads stdin itself).
```

--------------------------------

### GET /mcp (Stateful)

Source: https://github.com/supercorp-ai/supergateway/blob/main/_autodocs/api-reference/gateway-streamable-http.md

Stateful mode: GET opens the server-to-client event stream for a session.

```APIDOC
## GET /mcp

### Description
Opens the server-to-client event stream for a stateful session.

### Method
GET

### Endpoint
/mcp (or the configured `streamableHttpPath`)

### Parameters
#### Path Parameters
- None explicitly documented.

#### Query Parameters
- None explicitly documented.

#### Headers
- `Mcp-Session-Id` (string) - Required to identify the session for the event stream.

### Request Example
No explicit example provided in source.

### Response
#### Success Response (200)
- Server-to-client event stream (not explicitly detailed in source).

#### Response Example
No explicit example provided in source.
```

--------------------------------

### Build Supergateway Docker Image from Source

Source: https://github.com/supercorp-ai/supergateway/blob/main/README.md

Build the Docker image from the repository checkout, then run it with a filesystem MCP server.

```bash
npm ci
npm run pack:release
docker build -f docker/base.Dockerfile -t supergateway \
  --build-arg VERSION="$(node -p "require('./.release/manifest.json').version")" \
  --build-arg PACKAGE_SHA256="$(node -p "require('./.release/manifest.json').sha256")" .

docker run -it --rm -p 8000:8000 supergateway --stdio "npx -y @modelcontextprotocol/server-filesystem ."
```

--------------------------------

### Gating a gateway with an API key and tools

Source: https://github.com/supercorp-ai/supergateway/blob/main/_autodocs/api-reference/tools-and-security.md

Shows how to set up an Express app with API key authentication using requireApiKey and apiKeysOf, configure CORS, and add a health check before the key check. The example imports from local modules and uses a file reader for apiKeyFile.

```typescript
import { requireApiKey, apiKeysOf } from './lib/apiKey.js'
import { ToolNames } from './lib/toolNames.js'
import { headers } from './lib/headers.js'
import { corsOrigin } from './lib/corsOrigin.js'

const { keys } = apiKeysOf(
  { apiKey: ['k1'], apiKeyFile: '/run/secrets/keys' },
  process.env,
  (path) => require('node:fs').readFileSync(path, 'utf8'),
)
const app = express()
app.use(cors({ origin: corsOrigin({ argv: { cors: ['https://app.example.com'] } }) }))
app.get('/healthz', (_req, res) => res.send('ok')) // before the key check
app.use(requireApiKey(keys, logger))                 // after, so probes stay open
app.post('/mcp', (req, res) => { /* ... */ })
```

--------------------------------

### GET /mcp (Stateless)

Source: https://github.com/supercorp-ai/supergateway/blob/main/_autodocs/api-reference/gateway-streamable-http.md

Stateless mode: GET requests are not allowed and return 405 Method Not Allowed with a JSON-RPC -32000 error body.

```APIDOC
## GET /mcp

### Description
Returns 405 Method Not Allowed with a JSON-RPC -32000 error body because there is no session to stream from in stateless mode.

### Method
GET

### Endpoint
/mcp (or the configured `streamableHttpPath`)

### Parameters
#### Path Parameters
- None explicitly documented.

#### Query Parameters
- None explicitly documented.

### Request Example
No explicit example provided in source.

### Response
#### Error Response (405)
- JSON-RPC -32000 error body (not explicitly detailed in source).

#### Response Example
No explicit example provided in source.
```

--------------------------------

### Config file with multiple MCP servers (servers.json)

Source: https://github.com/supercorp-ai/supergateway/blob/main/README.md

Example config file defining a port and multiple MCP servers. Each server is served at /<name>. Supports JSONC comments and trailing commas. Environment variables like ${FILES_KEY} are replaced from the environment.

```jsonc
{
  "port": 8000,
  "mcpServers": {
    "git": { "command": "uvx", "args": ["mcp-server-git"] },
    "files": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "./my-folder"],
      "outputTransport": "streamableHttp",
      "apiKey": "${FILES_KEY}",
    },
  },
}
```

--------------------------------

### serverHealthOf function

Source: https://github.com/supercorp-ai/supergateway/blob/main/_autodocs/api-reference/serve-health-and-listening.md

Creates a ServerHealth instance when healthCheck is 'server', otherwise returns undefined. The probe uses a server started by start and returns a failure reason when the gateway is shutting down.

```TypeScript
export const serverHealthOf = (
  healthCheck: HealthCheck | undefined,
  children: { readonly closing: boolean },
  start: (logger: Logger) => StartPeer,
  logger: Logger,
) =>
  healthCheck === 'server'
    ? new ServerHealth(
        () =>
          children.closing
            ? Promise.resolve({ ok: false as const, reason: 'the gateway is shutting down' })
            : probeServer(start({ ...logger, error: () => {} })),
        logger,
      )
    : undefined
```

--------------------------------

### main() function in src/index.ts

Source: https://github.com/supercorp-ai/supergateway/blob/main/_autodocs/api-reference/invocation-and-exits.md

The process entry point that parses CLI arguments, resolves the invocation, and dispatches to serveSeveral or start. It catches errors and exits non-zero, and starts --exitWithProcess watching after shutdown handlers are registered.

```typescript
async function main() {
  const args = hideBin(process.argv)
  const cli = parseCli(args)
  const cliLogger = getLogger({
    logLevel: cli.logLevel,
    logFormat: cli.logFormat,
    outputTransport: cli.outputTransport as string,
  })
  // Warned, never refused: a refusal would stop deployments that start today.
  for (const warning of unknownArguments(args, cli)) cliLogger.error(warning)
  const run = invocation(args, cli, cliLogger)
  // The gateway-wide settings, which every entry's command line carries alike.
  const argv = 'argv' in run ? run.argv : run.servers[0].argv
  // No log line goes to stdout while it carries an entry's MCP messages.
  const logsBesideStdio = 'servers' in run && run.servers.some(isOnStdio)
  const loggerFor = (server?: string) => ...
  const { input } = orExit(logger, inputTransportOf(argv))
  const { host } = orExit(logger, hostOf(argv))
  const servers = keyedServers(run, argv, logger, loggerFor)
  const { pid } = orExit(logger, exitWithProcessOf(argv))
  announceStart(logger, run, argv, host, pid)

  try {
    if ('servers' in run)
      await serveSeveral(servers, run.healthEndpoints, argv.port, host, logger)
    else
      await start(input, argv, logger, { host, apiKeys: servers[0].apiKeys })
  } catch (err) {
    logger.error('Fatal error:', err)
    process.exit(1)
  }

  if (pid !== undefined)
    watchProcess(pid, {
      logger,
      onExit: () => requestShutdown(`Process ${pid} exited. Exiting...`),
    })
}

void main()
```
Tokens:
Raw