Advanced Features

This guide covers advanced RouterMCP CLI features including daemon mode, the proxy command, and session management.

Daemon Mode

Daemon mode allows multiple MCP clients to share a single gateway instance, reducing resource usage and maintaining session state.

How It Works

Run routermcp connect to connect to a daemon
If no daemon is running, one starts automatically in the background
The daemon runs an HTTP server on port 5151 (default)
The connect command proxies stdio to/from the daemon
The daemon shuts down after 10 seconds of idle

Usage

routermcp connect                    # Connect (auto-starts daemon)
routermcp connect --project /path    # Specific project directory
routermcp connect -v                 # Verbose logging

Manual Daemon Mode

Run the gateway explicitly as a daemon:

routermcp serve --daemon-mode --http 5151
routermcp serve --daemon-mode -v

Daemon Files

Daemon state is stored in ~/.routermcp/projects/<project-id>/:

File	Description
`daemon.pid`	Process ID of running daemon
`daemon.port`	HTTP port the daemon uses

Proxy Command

Proxy a stdio-based MCP server over HTTP without the full gateway configuration. Useful for exposing a single MCP server.

Basic Usage

# SSE proxy (default)
routermcp proxy --stdio "npx -y @modelcontextprotocol/server-filesystem ."

# Streamable HTTP (stateless)
routermcp proxy --stdio "node server.js" --outputTransport streamableHttp

# Streamable HTTP (stateful)
routermcp proxy --stdio "python mcp_server.py" --outputTransport streamableHttp --stateful

Proxy Options

Option	Default	Description
`--stdio <command>`	(required)	Command to spawn MCP server
`--outputTransport`	`sse`	Output: `sse` or `streamableHttp`
`-p, --port`	`8000`	HTTP server port
`--basePath`	`""`	Base path prefix
`--ssePath`	`/sse`	SSE endpoint path
`--messagePath`	`/message`	Message endpoint (SSE mode)
`--streamableHttpPath`	`/mcp`	Streamable HTTP endpoint
`--stateful`	`false`	Enable stateful sessions
`--sessionTimeout`	`60000`	Session timeout (ms)
`--healthEndpoint`	`/health`	Health check path
`--cors` / `--no-cors`	`true`	Enable/disable CORS
`--maxRestarts`	`3`	Max restart attempts

Transport Modes

SSE (Server-Sent Events)

Legacy but widely supported
Single child process shared across connections
Endpoints: GET /sse (connect), POST /message (send)

Streamable HTTP (Stateless)

Each request spawns a new child process
Best for simple, short-lived operations
Endpoint: POST /mcp

Streamable HTTP (Stateful)

Sessions persist with dedicated process per session
Supports server-initiated notifications
Endpoints: POST /mcp, GET /mcp (SSE), DELETE /mcp

Session Management

When running in HTTP mode, RouterMCP manages sessions for connected clients.

Session Behavior

Each connected client gets an isolated session
Sessions maintain state across requests
Sessions timeout after inactivity (default: 5 minutes)
Each session has its own upstream server connections

Configuration

{
  "session": {
    "timeout": 300,      // Seconds (default: 300)
    "max_sessions": 25   // Maximum concurrent (default: 25)
  }
}

Error Handling

Name Collisions

If multiple servers expose tools with the same name, the gateway fails to start with a collision error.

Resolution:

Use filtering to expose only unique names
Rename tools at the upstream server level
Disable conflicting servers

Graceful Degradation

If an upstream server fails to connect:

Gateway continues with available servers
Failed servers are logged with error details
Their tools/resources/prompts are not exposed
Restart gateway after fixing the configuration

CLI Reference

Global Options

Option	Description
`-v, --verbose`	Enable verbose logging
`-h, --help`	Show help message

Serve Options

Option	Description
`-c, --config <path>`	Config file path
`--stdio`	Use stdio transport (default)
`--http <port>`	Use HTTP on specified port
`--daemon-mode`	Run as background daemon
`--socket <path>`	Unix socket path (daemon, non-Windows)

Connect Options

Option	Description
`-c, --config <path>`	Config file path
`--project <path>`	Project directory for daemon

Features Summary

Feature	Description
MCP Gateway	Proxy multiple upstream servers
Code Mode	JavaScript execution in WebAssembly sandbox
Session Multiplexing	Isolated sessions for HTTP clients
Daemon Mode	Background process with auto-startup
Stdio-to-HTTP Proxy	Convert stdio servers to HTTP
Tool Filtering	Allow/deny with exact names or globs
Resource Filtering	Same filtering for resources
Prompt Filtering	Same filtering for prompts
Multiple Transports	Stdio and HTTP for both directions
Graceful Degradation	Continue if some servers fail
Auto-Restart	Restart child processes on failure
Interactive Config	CLI wizard for configuration
Tunnel Support	Cloudflare and ngrok integration
Environment Variables	`${VAR}` substitution in config

Advanced Features

On this page