@srbhptl39/mcp-superassistant-proxy

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:

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

{
  "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:

   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.