mux

One MCP to rule them all.

A lightweight gateway that routes your AI to any MCP server on demand. 4 tools. Zero re-auth. Everything else spawned when needed.

The Problem

Your AI drowns in 50+ tools
it doesn't need right now.

50+
Tools in context

Every MCP server dumps its full schema into your AI's working memory.

800MB
RAM wasted

15 idle processes consuming resources for tools you call once a day.

∞
Re-auth loops

OAuth sessions die on disable. Browser popup every time you re-enable.

The Solution

4 tools. Always.
Everything else, on demand.

0%
Less context
0MB
Idle memory
0
Re-auth prompts
How it works
1AI calls mux_call_tool2Mux routes to server3Server responds4Idle → killed after 5 min

Architecture

One gateway. Every server.

AIClientmux4 toolsGitLab8 toolsJira12 toolsElastic10 toolsDatadog9 toolsSlack5 toolsSitecore15 toolsstdioon demand

Features

Built for the real world.

Lazy Spawn

Servers start on first call. Zero overhead until needed.

Idle Reaper

Kills unused connections after 5 min. RAM reclaimed.

OAuth Cached

Tokens persist. Auth once, use forever.

Schema Cache

Tools remembered after disconnect. Instant reconnect.

Auto Keywords

Intent routing from real tool discovery.

Hot Reload

Edit registry, no restart. Live in 2 seconds.

Metrics

Context savings, response times, auth efficiency.

Any Client

Kiro, Cursor, Claude Desktop. Any stdio MCP.

MCP Tools

4 tools. That's the entire surface.

Regardless of how many downstream servers exist, your AI only sees these 4 tools in its context.

Response
[
  { "name": "gitlab", "status": "active", "tools": 8 },
  { "name": "jira", "status": "idle", "keywords": ["ticket","sprint"] },
  { "name": "elastic", "status": "idle", "tools": ["search_documents","get_index"] }
]

CLI Reference

Full control from your terminal.

mux-cli setup
mux-cli add <name>
mux-cli remove <name>
mux-cli auth [--all]
mux-cli health
mux-cli list
mux-cli status
mux-cli metrics
mux-cli keywords [name]
mux-cli update

Authentication

Auth once. Cached forever.

Smart detection — only triggers OAuth when the server actually supports it. Live countdown timer. Instant resolution.

1

Tool call arrives for HTTP server

2

Try connecting without auth — works for API-key servers instantly

3

If 401 → probe OAuth discovery endpoint on server

4

OAuth found → browser auth with live countdown timer

5

Token cached. Resolves immediately when auth completes.

TypeConfigBehavior
Env tokensenv: { "TOKEN": "${VAR}" }From shell environment
Static headersheaders: { "X-Key": "${KEY}" }Injected into HTTP
OAuth (browser)Server has OAuth discoveryBrowser → authorize → cached
No OAuthServer returns 401, no discoveryFail fast with clear error

Configuration

One JSON file. Hot-reloaded.

~/.mux/servers.json
{
  "servers": {
    "gitlab": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@zereight/mcp-gitlab"],
      "env": { "GITLAB_TOKEN": "${GITLAB_TOKEN}" },
      "keywords": ["merge request", "pipeline"],
      "idleTimeoutMs": 300000
    }
  }
}
Environment Variables
MUX_LOG_LEVEL
error | warn | info | debuginfo
MUX_LOG_TO_FILE
Write logs to ~/.mux/mux.logfalse
MUX_REGISTRY_PATH
Path to registry~/.mux/servers.json
MUX_TOKEN_STORE_PATH
OAuth token cache~/.mux/tokens.json
MUX_DEFAULT_IDLE_TIMEOUT
Idle timeout (ms)300000

Connection Lifecycle

Spawn. Use. Kill. Repeat.

IDLE

Registered, not running

→
ACTIVE

Connected, handling calls

→
KILLED

Idle timeout, disconnected

Idle Timeout

Connections killed after 5 min of inactivity. Configurable per server.

Hot Reload

Edit ~/.mux/servers.json — changes apply in 2 seconds, no restart.

Graceful Shutdown

On SIGTERM: disconnect all, kill children, exit clean.

Install

Get started in seconds.

One command installs globally. Then run mux-cli from anywhere.

1Install
npm install -g mux-mcp-gateway
2Run
mux-cli
3Done

Mux imports your existing servers, patches your AI client config, and runs a health check. Your AI now sees 4 tools instead of 50+.

Comparison

Before vs After.

MetricWithout MuxWith Mux
Tools in context50+4
Running processes15+1 + on-demand
RAM (idle)~800MB~50MB
OAuth re-authEvery enable/disableNever (cached)
Add new serverEdit config + restartEdit JSON (hot-reload)
Cold startN/A (always on)1-3s (spawn)
Warm call overhead0ms<100ms

Tech Stack

Under the hood.

RuntimeNode.js 20+
LanguageTypeScript 5.7
MCP Protocol@modelcontextprotocol/sdk 1.12.1
Buildtsup (ESM)
Transport ↑stdio (to AI client)
Transport ↓stdio + StreamableHTTP
Token StorageJSON file (chmod 600)
OAuthAuthorization Code + PKCE

Supported Clients

Works with everything.

Kiro CLI~/.kiro/settings/mcp.json
Kiro IDE~/.kiro/settings/mcp.json
Cursor~/.cursor/mcp.json
Claude Desktop~/Library/.../config.json
Any stdio clientCustom