mcp-mux
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
mcp-mux
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.
Problem
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 │
└──────┘ └────────┘ └────────┘Related MCP server: MCP Proxy Server
How it works
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
# Install from GitHub
npm install -g github:jasonwarta/mcp-mux
# Or use npx directly from GitHub (no install)
npx github:jasonwarta/mcp-muxSetup
1. Create .mcp-mux.json in your project root
{
"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
}
}
}2. Point Claude Code at the mux
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.
Configuration
Server options
Field | Type | Default | Description |
| string | required | Executable to spawn |
| string[] |
| Arguments to the command |
| object |
| Additional environment variables |
| string | project root | Working directory for the server |
|
|
| Shared: one process for all sessions. Per-session: one per shim (for stateful servers like Playwright) |
| boolean |
| If true, don't spawn until first |
| integer |
| Max consecutive restart attempts before marking as failed |
| integer |
| Initial backoff (doubles each failure, capped at 30s) |
Global options
Field | Type | Default | Description |
| integer |
| Broker shuts down after this many ms with no connected shims |
| integer |
| Timeout for individual tool call requests |
Server modes
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.
Tool naming
Tools are namespaced to avoid collisions. A tool named status from server pare-git appears in Claude Code as:
mcp__mcp-mux__pare-git__statusThe format is mcp__<mcp-server-name>__<backend-server>__<tool>.
CLI
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.
How request routing works
Claude Code sends
tools/callwith a namespaced tool nameShim 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
Crash recovery
Backend servers that crash are automatically restarted with exponential backoff
After
maxRestartsconsecutive failures, the server is marked as failedIn-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
Socket paths
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.
Requirements
Node.js >= 20
Any stdio MCP server as a backend
Zero npm dependencies. Uses only Node.js built-in modules.
License
MIT
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Toolstile is a managed MCP gateway that connects remote MCP servers behind one endpoint, with per-agent permissions, shared accounts and activity logs. Connect at https://mcp.toolstile.com/mcp over Streamable HTTP with OAuth; sign in at https://toolstile.com, select a workspace and connect your upstream servers. Available tools, resources and prompts depend on that workspace and the agent's granted access.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
- aXDeprecatedio.github.ax-platform
Agent-native collaboration network: orchestrate a team of long-running agents from any MCP client.
Hosted MCP runtime where your agent publishes its own tools by tool call and keeps working.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables MCP clients to list and call tools from multiple configured servers while each backend starts only on first use, is shared across sessions, and stops when idle. This reduces memory and process overhead without changing tool names or permissions.15 npmMIT
- AlicenseNot gradedqualityAmaintenanceEnables connecting to and managing multiple backend MCP resource servers while routing tool and resource requests to the appropriate server and exposing their combined capabilities through a unified SSE, Streamable HTTP, or Stdio interface.120 npmMIT
- FlicenseNot gradedqualityAmaintenanceAggregates multiple backend MCP servers (Stdio, SSE, and Streamable HTTP) and exposes their combined tools and resources through a single unified SSE or Streamable HTTP endpoint, or as a standalone Stdio server. It routes tool calls and resource requests to the right backend and offers optional web-based admin, authentication, and per-tool control.-
- FlicenseNot gradedqualityAmaintenanceA meta-MCP server that aggregates and proxies other MCP servers, letting LLMs search for, add, configure, enable, disable, and bundle backend servers at runtime. Tools from those servers are automatically exposed under unified prefixes, with persistent configuration, health checks, and support for stdio, HTTP, and hybrid transports.-