mcpmux

Dynamic MCP multiplexer — one gateway, many upstream MCP servers.

mcpmux sits between any MCP client (Cursor, Claude Desktop, Codex, VS Code, Windsurf, etc.) and your upstream MCP servers. Instead of exposing hundreds of tools directly to the model, it exposes a small fixed interface and discovers the right tool on demand.

The Problem

MCP clients receive the full tool inventory from every connected server in tools/list. With multiple servers this can mean hundreds of tool schemas injected into every prompt — burning tokens and degrading model performance.

How mcpmux Solves It

mcpmux exposes only 5 tools to the client regardless of how many upstream tools exist:

Gateway Tool	Purpose
discover_tools	Natural-language query → ranked tool candidates
call_discovered_tool	Execute a discovered tool by ID
refresh_tool_catalog	Reload upstream catalogs
gateway_stats	Usage metrics
upstream_status	Server connection status

The model calls discover_tools first, picks from the results, then calls call_discovered_tool. In benchmarks with 111 upstream tools, this reduced tool-context tokens by ~97%.

Features

• Works as a standard MCP stdio server — compatible with any MCP client
• Proxies to multiple upstream MCP stdio servers
• Two-stage discovery: query first, execute second
• Scoring by verb, domain, intent, history, cost, and risk
• Optional tool filtering per upstream (includeTools, excludeTools)
• Per-tool success/failure tracking for ranking improvement
• JSON and YAML config support

Quick Start

npx mcpmux --config ./gateway.config.json

No install needed — npx downloads and runs it directly.

Global Install

npm install -g mcpmux
mcpmux --config ./gateway.config.json

Local Project Install

npm install mcpmux
npx mcpmux --config ./gateway.config.json

Configure

Create a gateway.config.json (or .yaml):

{
  "routing": {
    "topN": 5,
    "minimumScore": 0.2,
    "allowHighRisk": false,
    "cacheTtlMs": 2700000
  },
  "servers": [
    {
      "id": "jira",
      "command": "npx",
      "args": ["-y", "mcp-remote@latest", "https://mcp.atlassian.com/v1/mcp"],
      "defaultDomain": "atlassian",
      "excludeTools": ["delete", "remove"]
    },
    {
      "id": "github",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "defaultDomain": "github"
    }
  ]
}

An example config is included in the package: gateway.config.example.json.

Routing Options

Field	Type	Default	Description
topN	number	3	Maximum number of tool candidates returned by discover_tools.
minimumScore	number	0.2	Minimum relevance score (0–1) a tool must reach to appear in results. Lower values return more candidates; higher values are stricter.
allowHighRisk	boolean	false	Include tools classified as high-risk (destructive operations like delete, drop, remove). Keep false unless you explicitly need them.
cacheTtlMs	number	2700000 (45 min)	How long the gateway caches upstream tool catalogs before re-fetching, in milliseconds.

Server Options

Field	Type	Required	Description
id	string	Yes	Unique identifier for the upstream server. Used as prefix in tool IDs (e.g. jira:search_issues).
command	string	Yes	Command to spawn the upstream MCP server process.
args	string[]	No	Arguments passed to the command. Defaults to [].
cwd	string	No	Working directory for the upstream server process.
env	object	No	Additional environment variables passed to the upstream process.
defaultDomain	string	No	Domain hint for scoring (e.g. "atlassian", "github"). Improves ranking accuracy for domain-specific queries.
includeTools	string[]	No	Allowlist of tool name patterns. Only matching tools are exposed through the gateway.
excludeTools	string[]	No	Blocklist of tool name patterns. Matching tools are hidden from discovery.

Add to MCP Clients

Point your MCP client to mcpmux as a stdio server. The configuration format below works with most clients.

Cursor / VS Code / Claude Desktop / Windsurf

{
  "mcpServers": {
    "mcpmux": {
      "command": "npx",
      "args": ["-y", "mcpmux", "--config", "/absolute/path/to/gateway.config.json"]
    }
  }
}

Codex CLI / Claude CLI

codex mcp add mcpmux -- npx -y mcpmux --config /path/to/gateway.config.json
claude mcp add mcpmux -- npx -y mcpmux --config /path/to/gateway.config.json

Any MCP-compatible Client

mcpmux uses standard MCP stdio transport. If your client supports MCP servers, point it to:

• Command: npx
• Args: -y mcpmux --config /path/to/gateway.config.json

How Models Use It

1. Call discover_tools with a natural-language task description.
2. Pick a toolId from the ranked candidates.
3. Call call_discovered_tool with the toolId and arguments.
4. Retry with another candidate if needed.

Security

• High-risk tools are filtered out by default (allowHighRisk: false)
• Use excludeTools in config for irreversible operations (delete, remove, etc.)
• Run the gateway with least-privilege credentials for upstream servers

Limitations

• Upstream servers must support MCP stdio transport
• Proxies tools only (not resources or prompts)
• Ranking is heuristic — tune by domain and priors over time

Development

npm run check              # Type-check
npm run lint               # Lint
npm run format             # Format
npm run test               # Unit tests
npm run smoke              # End-to-end smoke test
npm run measure-savings    # Token savings report for your config

Contributing

Contributions are welcome! Please read the contributing guide to get started. This project follows the Contributor Covenant Code of Conduct.

To report a security vulnerability, see our security policy. For a history of changes, see the changelog.

License

MIT