A stdio-to-stdio MCP multiplexer that presents itself to Claude Code as a single MCP server while sharing backend server processes across sessions via a background broker.
Claude Code spawns every configured stdio MCP server as a child process per session. With 9 servers and 12 concurrent sessions, that's 108+ long-lived Node processes.
mcp-mux reduces this to N shim processes + 9 shared servers, regardless of session count.
Claude Code Session A Claude Code Session B
│ │
stdin/stdout stdin/stdout
│ │
┌────▼─────┐ ┌─────▼────┐
│ Shim A │ │ Shim B │
│ (stdio) │ │ (stdio) │
└────┬─────┘ └─────┬────┘
│ local socket │
└──────────────┬─────────────────────┘
│
┌────────▼────────┐
│ Broker │
│ (background) │
└───┬────┬────┬───┘
│ │ │
┌─────▼┐ ┌▼────▼──┐ ┌────────┐
│Server│ │Server │ │ etc... │
│ A │ │ B │ │ │
│stdio │ │stdio │ │ stdio │
└──────┘ └────────┘ └────────┘
- Shim — Lightweight stdio process spawned by Claude Code (one per session). Speaks MCP over stdin/stdout to Claude Code, connects to the broker over a local socket.
- Broker — Long-lived background process managing all backend MCP servers. Auto-started by the first shim, auto-exits after 5 minutes of inactivity.
The shim aggregates tools from all backend servers into a single namespace, routes tools/call requests to the correct backend, and handles request ID remapping so multiple sessions can share servers without conflicts.
# Install from GitHub
npm install -g github:jasonwarta/mcp-mux
# Or use npx directly from GitHub (no install)
npx github:jasonwarta/mcp-mux{
"servers": {
"pare-git": {
"command": "npx",
"args": ["-y", "@paretools/git"]
},
"pare-test": {
"command": "npx",
"args": ["-y", "@paretools/test"]
},
"playwright": {
"command": "npx",
"args": ["@playwright/mcp@latest"],
"mode": "per-session",
"lazy": true
}
}
}In your .mcp.json:
{
"mcpServers": {
"mcp-mux": {
"type": "stdio",
"command": "npx",
"args": ["github:jasonwarta/mcp-mux"]
}
}
}Or if you cloned the repo locally:
{
"mcpServers": {
"mcp-mux": {
"type": "stdio",
"command": "node",
"args": ["/path/to/mcp-mux/src/shim.mjs"]
}
}
}That's it. The shim auto-starts the broker on first use. No daemon management required.
| Field | Type | Default | Description |
|---|---|---|---|
command |
string | required | Executable to spawn |
args |
string[] | [] |
Arguments to the command |
env |
object | {} |
Additional environment variables |
cwd |
string | project root | Working directory for the server |
mode |
"shared" | "per-session" |
"shared" |
Shared: one process for all sessions. Per-session: one per shim (for stateful servers like Playwright) |
lazy |
boolean | false |
If true, don't spawn until first tools/call. Tools are probed at startup then the process is killed. |
maxRestarts |
integer | 5 |
Max consecutive restart attempts before marking as failed |
restartBackoffMs |
integer | 1000 |
Initial backoff (doubles each failure, capped at 30s) |
| Field | Type | Default | Description |
|---|---|---|---|
idleTimeoutMs |
integer | 300000 |
Broker shuts down after this many ms with no connected shims |
requestTimeoutMs |
integer | 60000 |
Timeout for individual tool call requests |
Shared (default) — One server process handles all sessions. Good for stateless tools (git, test runners, linters). The backend servers must accept explicit path/cwd parameters per request rather than relying on process.cwd().
Per-session — One server process per Claude Code session. Required for stateful servers that maintain session context (e.g., Playwright browser sessions, code-graph indexes). The process is spawned on first tool call and killed when the session disconnects.
Lazy — The server is probed for capabilities at broker startup (so its tools appear in the tool list), then the process is killed. A real instance is spawned on the first tools/call. Works with both shared and per-session modes. Good for heavy, rarely-used servers.
Tools are namespaced to avoid collisions. A tool named status from server pare-git appears in Claude Code as:
mcp__mcp-mux__pare-git__status
The format is mcp__<mcp-server-name>__<backend-server>__<tool>.
The shim doubles as a CLI for broker management:
# Check broker status (server states, connected shims, uptime)
npx github:jasonwarta/mcp-mux status
# Stop the broker
npx github:jasonwarta/mcp-mux stop
# Restart the broker
npx github:jasonwarta/mcp-mux restartIf installed globally or cloned locally, replace npx github:jasonwarta/mcp-mux with mcp-mux or node src/shim.mjs.
All commands accept --config <path> to specify an alternate config file.
- Claude Code sends
tools/callwith a namespaced tool name - Shim looks up the routing table to find the backend server
- Shim remaps the tool name back to the original and forwards to the broker
- Broker remaps the request ID to a unique internal ID (so multiple shims can share a server without ID collisions)
- Backend server processes the request and responds
- Broker remaps the ID back and routes the response to the correct shim
- Shim returns the response to Claude Code on stdout
- Backend servers that crash are automatically restarted with exponential backoff
- After
maxRestartsconsecutive failures, the server is marked as failed - In-flight requests to a crashed server get an error response (not a hang)
- If the broker itself crashes, the next shim connection auto-starts a new one
The broker listens on a local socket derived from the config file path:
- Linux/macOS:
$XDG_RUNTIME_DIR/mcp-mux-<hash>.sock(or/tmp/) - Windows:
\\.\pipe\mcp-mux-<hash>
Where <hash> is the first 8 chars of SHA-256 of the absolute config path. Different projects get different sockets.
- Node.js >= 20
- Any stdio MCP server as a backend
Zero npm dependencies. Uses only Node.js built-in modules.
MIT