# MCP SuperAssistant Proxy

MCP SuperAssistant Proxy lets you run multiple **MCP stdio-based** and **SSE-based** servers and expose them through a single SSE endpoint. This allows MCP SuperAssistant and other tools to connect to multiple remote MCP servers and tools via a unified proxy.

## Installation & Usage

Run MCP SuperAssistant Proxy via `npx`:

```bash
npx -y @srbhptl39/mcp-superassistant-proxy@latest --config path/to/config.json
```

### CLI Options

- `--config, -c <path>`: **(required)** Path to a JSON configuration file (see below)
- `--port <number>`: Port to run the proxy server on (default: `3006`)
- `--baseUrl <url>`: Base URL for SSE clients (default: `http://localhost:<port>`)
- `--ssePath <path>`: Path for SSE subscriptions (default: `/sse`)
- `--messagePath <path>`: Path for SSE messages (default: `/message`)
- `--logLevel <info|none>`: Set logging level (default: `info`)
- `--outputTransport stdio | sse | ws | streamableHttp`: Output MCP transport (default: `sse` with `--stdio` or `--config`, `stdio` with `--sse` or `--streamableHttp`)
- `--ssePath "/sse"`: Path for SSE subscriptions (stdio→SSE, config→SSE modes, default: `/sse`)
- `--messagePath "/message"`: Path for messages (stdio→SSE, stdio→WS, config→SSE, config→WS modes, default: `/message`)
- `--streamableHttpPath "/mcp"`: Path for Streamable HTTP (stdio→StreamableHttp, config→StreamableHttp modes, default: `/mcp`)
- `--stateful`: Run StreamableHttp in stateful mode (stdio→StreamableHttp, config→StreamableHttp modes)
- `--sessionTimeout 60000`: Session timeout in milliseconds (stateful StreamableHttp modes only)
- `--header "x-user-id: 123"`: Add one or more headers (stdio→SSE, SSE→stdio, or Streamable HTTP→stdio mode; can be used multiple times)
- `--oauth2Bearer "some-access-token"`: Adds an `Authorization` header with the provided Bearer token
- `--logLevel debug | info | none`: Controls logging level (default: `info`). Use `debug` for more verbose logs, `none` to suppress all logs.

- `--cors`: Enable CORS (default: `true`)
- `--healthEndpoint <path>`: One or more endpoints returning `"ok"` (can be used multiple times)
- `--timeout <ms>`: Connection timeout in milliseconds (default: `30000`)

## Configuration File

The configuration file is a JSON file specifying which MCP servers to connect to. Each server can be either a stdio-based server (run as a subprocess) or an SSE-based server (remote URL).

### Example `config.json`

```json
{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@suekou/mcp-notion-server"],
      "env": {
        "NOTION_API_TOKEN": "<your_notion_token_here>"
      }
    },
    "gmail": {
      "url": "https://mcp.composio.dev/gmail/xxxx"
    },
    "youtube-subtitle-downloader": {
      "command": "bun",
      "args": [
        "run",
        "/path/to/mcp-youtube/src/index.ts"
      ]
    },
    "desktop-commander": {
      "command": "npx",
      "args": ["-y", "@wonderwhy-er/desktop-commander"]
    },
    "iterm-mcp": {
      "command": "npx",
      "args": ["-y", "iterm-mcp"]
    }
  }
}
```

- Each key under `mcpServers` is a unique name for the server.
- For stdio-based servers, specify `command`, `args`, and optionally `env`.
- For SSE-based servers, specify `url`.

## Endpoints

Once started, the proxy exposes:
- **SSE endpoint**: `http://localhost:<port>/sse`
- **POST messages**: `http://localhost:<port>/message`
- **Streamable HTTP endpoint**: `http://localhost:<port>/mcp`
- **Websocket endpoint**: `ws://localhost:<port>/message`

(You can customize the paths with `--ssePath` and `--messagePath`.)

## Example

1. **Create a config file** (e.g., `config.json`) as shown above.
2. **Run MCP SuperAssistant Proxy**:
   ```bash
   npx -y @srbhptl39/mcp-superassistant-proxy@latest --config config.json --port 3006
   ```

## Why MCP?

[Model Context Protocol](https://spec.modelcontextprotocol.io/) standardizes how AI tools exchange data. If your MCP server only speaks stdio, MCP SuperAssistant Proxy exposes an SSE-based interface so remote clients (and tools like MCP Inspector or Claude Desktop) can connect without extra server changes. It also allows you to aggregate multiple MCP servers behind a single endpoint.

## Advanced Configuration

MCP SuperAssistant Proxy is designed with modularity in mind:
- Supports both stdio and SSE MCP servers in one config.
- Automatically derives the JSON‑RPC version from incoming requests, ensuring future compatibility.
- Package information (name and version) is retransmitted where possible.
- Stdio-to-SSE mode uses standard logs and SSE-to-Stdio mode logs via stderr (as otherwise it would prevent stdio functionality).
- The SSE-to-SSE mode provides automatic reconnection with backoff if the remote server connection is lost.
- Health endpoints can be added for monitoring.

---

For more details, see the [Model Context Protocol documentation](https://modelcontextprotocol.io/).

## Acknowledgments

Special thanks to [SuperGateway](https://github.com/supercorp-ai/supergateway) for starter code.