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

graph LR
    Client[AI Client<br/>Kiro/Cursor] --> GitLab[GitLab MCP<br/>8 tools]
    Client --> Jira[Jira MCP<br/>12 tools]
    Client --> Elastic[Elasticsearch<br/>6 tools]
    Client --> Datadog[Datadog MCP<br/>9 tools]
    Client --> Sitecore[Sitecore MCP<br/>15 tools]
    Client --> Slack[Slack MCP<br/>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

graph LR
    Client[AI Client<br/>Kiro/Cursor] --> Mux[MUX<br/>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

npm install -g mux-mcp-gateway

Or via the install script:

curl -sL https://mux-gateway.vercel.app/install.sh | bash

Then run:

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 | | | servers.json schema, environment variables, hot-reload registry | | | Setup guides for Kiro, Cursor, and Claude Desktop | | | System design, pool manager, transport layer, data flow | | | mux_list_servers · mux_call_tool · mux_find_tool · mux_status | | | OAuth flow, token caching, persistent sessions across restarts | | | Spawn → active → idle → reaped state machine | | | Context reduction, resource savings, auth improvements | | | Runtime, build tools, supported transports | | | Project structure, test suite, local dev workflow |

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

mux-cli setup              # Import from existing mcp.json
mux-cli add <name> '<json>'  # Add a server
mux-cli remove <name>      # 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

License

MIT