Docs — Mux MCP Gateway

One MCP to rule them all.
_{A lightweight gateway that multiplexes multiple MCP servers behind a single always-on endpoint.}

Visit the Website

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

Loading diagram...

After Mux

Loading diagram...

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

Author

License

MIT