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
`

$3

- --config, -c : (required) Path to a JSON configuration file (see below)
- --port : Port to run the proxy server on (default: 3006)
- --baseUrl : Base URL for SSE clients (default: http://localhost:)
- --ssePath : Path for SSE subscriptions (default: /sse)
- --messagePath : Path for SSE messages (default: /message)
- --logLevel : 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 : One or more endpoints returning "ok" (can be used multiple times)
- --timeout : 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).

$3

`json
{
"mcpServers": {
"notion": {
"command": "npx",
"args": ["-y", "@suekou/mcp-notion-server"],
"env": {
"NOTION_API_TOKEN": ""
}
},
"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:/sse
- POST messages: http://localhost:/message
- Streamable HTTP endpoint: http://localhost:/mcp
- Websocket endpoint: ws://localhost:/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 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.

Acknowledgments

Special thanks to SuperGateway for starter code.