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