---
## Why Mux?
> [!IMPORTANT]
> Running 15+ MCP servers = **50+ tools** in your AI's context window, wasted RAM, and constant OAuth re-auth. Mux reduces this to **4 tools, 1 process, zero re-auth**.
Modern AI editors (Kiro, Cursor, Claude Desktop) connect to MCP servers for tool access. In real-world setups, you accumulate **10-20+ servers** — GitLab, Jira, Elasticsearch, Datadog, Sitecore, Slack, and more. Running them all simultaneously creates three critical issues:
| Issue | Impact |
|:------|:-------|
| **Context bloat** | Every server's tool schemas consume AI context tokens. 15 servers = 50+ tools competing for attention. |
| **Resource waste** | Each server runs as a separate process consuming RAM, even if unused for hours. |
| **Re-authentication** | OAuth-based servers lose their session when disabled, requiring browser re-auth every single time. |
---
## The Solution
Mux sits between your AI client and all your MCP servers. It exposes **exactly 4 tools** — regardless of how many downstream servers exist. Servers are spawned on demand, killed when idle, and their auth tokens persist across sessions.
> ### Before Mux
```mermaid
graph LR
Client[AI Client Kiro/Cursor] --> GitLab[GitLab MCP 8 tools]
Client --> Jira[Jira MCP 12 tools]
Client --> Elastic[Elasticsearch 6 tools]
Client --> Datadog[Datadog MCP 9 tools]
Client --> Sitecore[Sitecore MCP 15 tools]
Client --> Slack[Slack MCP 5 tools]
style Client fill:#1a1a2e,stroke:#a78bfa,color:#fff
style GitLab fill:#2d2d44,stroke:#f59e0b,color:#fff
style Jira fill:#2d2d44,stroke:#f59e0b,color:#fff
style Elastic fill:#2d2d44,stroke:#f59e0b,color:#fff
style Datadog fill:#2d2d44,stroke:#f59e0b,color:#fff
style Sitecore fill:#2d2d44,stroke:#f59e0b,color:#fff
style Slack fill:#2d2d44,stroke:#f59e0b,color:#fff
```
> ### After Mux
```mermaid
graph LR
Client[AI Client Kiro/Cursor] --> Mux[MUX 4 tools]
Mux -.->|on demand| GitLab[GitLab MCP]
Mux -.->|on demand| Jira[Jira MCP]
Mux -.->|on demand| Elastic[Elasticsearch]
Mux -.->|on demand| Datadog[Datadog MCP]
style Client fill:#1a1a2e,stroke:#a78bfa,color:#fff
style Mux fill:#0d3b66,stroke:#a78bfa,color:#fff,stroke-width:3px
style GitLab fill:#1a1a2e,stroke:#10b981,color:#fff
style Jira fill:#1a1a2e,stroke:#10b981,color:#fff
style Elastic fill:#1a1a2e,stroke:#10b981,color:#fff
style Datadog fill:#1a1a2e,stroke:#10b981,color:#fff
```
---
## Install
```bash
npm install -g mux-mcp-gateway
```
Or via the install script:
```bash
curl -sL https://mux-gateway.vercel.app/install.sh | bash
```
Then run:
```bash
mux-cli
```
That's it. Mux imports your existing MCP config, patches your AI client, and you're done.
---
## How It Works
| Step | What happens |
|------|-------------|
| 1 | AI calls `mux_call_tool("gitlab", "list_mrs", {...})` |
| 2 | Mux spawns GitLab MCP server (if not running) |
| 3 | Routes the call, returns the result |
| 4 | After 5 min idle → kills the connection |
Your AI only sees **4 tools** regardless of how many servers are registered.
---
## Documentation
| | |
|:--|:--|
| | [All `mux-cli` commands — setup, add, remove, auth, health, metrics, keywords](docs/cli.md) |
| | [`servers.json` schema, environment variables, hot-reload registry](docs/config.md) |
| | [Setup guides for Kiro, Cursor, and Claude Desktop](docs/clients.md) |
| | [System design, pool manager, transport layer, data flow](docs/architecture.md) |
| | [`mux_list_servers` · `mux_call_tool` · `mux_find_tool` · `mux_status`](docs/tools.md) |
| | [OAuth flow, token caching, persistent sessions across restarts](docs/auth.md) |
| | [Spawn → active → idle → reaped state machine](docs/lifecycle.md) |
| | [Context reduction, resource savings, auth improvements](docs/comparison.md) |
| | [Runtime, build tools, supported transports](docs/tech-stack.md) |
| | [Project structure, test suite, local dev workflow](docs/development.md) |
---
## Why run locally?
Mux runs as a local stdio process by design. Your credentials (tokens, API keys) stay on your machine — they're injected via environment variables and never leave your shell session. Downstream servers enforce access based on **your** tokens, so Mux has no elevated privileges.
This means:
- No shared credential store to secure
- No multi-tenancy complexity
- No token management service needed
- OAuth tokens persist in `~/.mux/tokens.json` (AES-256-GCM encrypted, 0600 permissions)
---
## Quick CLI Reference
```bash
mux-cli setup # Import from existing mcp.json
mux-cli add '' # Add a server
mux-cli remove # Remove a server
mux-cli auth --all # Authorize all HTTP servers
mux-cli health # Health check
mux-cli list # Show servers + status
mux-cli metrics # Usage insights dashboard
mux-cli keywords [name] # View/edit keywords
mux-cli update # Update to latest version
mux-cli uninstall # Remove Mux completely
```
---
## Author
> ### After Mux
```mermaid
graph LR
Client[AI Client
---
## Install
```bash
npm install -g mux-mcp-gateway
```
Or via the install script:
```bash
curl -sL https://mux-gateway.vercel.app/install.sh | bash
```
Then run:
```bash
mux-cli
```
That's it. Mux imports your existing MCP config, patches your AI client, and you're done.
---
## How It Works
| Step | What happens |
|------|-------------|
| 1 | AI calls `mux_call_tool("gitlab", "list_mrs", {...})` |
| 2 | Mux spawns GitLab MCP server (if not running) |
| 3 | Routes the call, returns the result |
| 4 | After 5 min idle → kills the connection |
Your AI only sees **4 tools** regardless of how many servers are registered.
---
## Documentation
| | |
|:--|:--|
| 
| [All `mux-cli` commands — setup, add, remove, auth, health, metrics, keywords](docs/cli.md) |
| 
| [`servers.json` schema, environment variables, hot-reload registry](docs/config.md) |
| 
| [Setup guides for Kiro, Cursor, and Claude Desktop](docs/clients.md) |
| 
| [System design, pool manager, transport layer, data flow](docs/architecture.md) |
| 
| [`mux_list_servers` · `mux_call_tool` · `mux_find_tool` · `mux_status`](docs/tools.md) |
| 
| [OAuth flow, token caching, persistent sessions across restarts](docs/auth.md) |
| 
| [Spawn → active → idle → reaped state machine](docs/lifecycle.md) |
| 
| [Context reduction, resource savings, auth improvements](docs/comparison.md) |
| 
| [Runtime, build tools, supported transports](docs/tech-stack.md) |
| 
| [Project structure, test suite, local dev workflow](docs/development.md) |
---
## Why run locally?
Mux runs as a local stdio process by design. Your credentials (tokens, API keys) stay on your machine — they're injected via environment variables and never leave your shell session. Downstream servers enforce access based on **your** tokens, so Mux has no elevated privileges.
This means:
- No shared credential store to secure
- No multi-tenancy complexity
- No token management service needed
- OAuth tokens persist in `~/.mux/tokens.json` (AES-256-GCM encrypted, 0600 permissions)
---
## Quick CLI Reference
```bash
mux-cli setup # Import from existing mcp.json
mux-cli add 
