mcpmu (μ)

A multiplexing MCP server that aggregates multiple MCP servers behind a single stdio MCP server.

Unlike typical MCP setups where each coding agent needs its own server configurations, mcpmu acts as a meta-server: you configure all your MCP servers once, then expose them as a unified endpoint to any agent that supports the Model Context Protocol. Add one entry to Claude Code, Cursor, Windsurf, or any MCP-compatible tool and instantly gain access to your entire MCP ecosystem.

Key differentiators:

• Single configuration, universal access — Define servers once, use everywhere
• Namespace profiles — Group servers by context (work, personal, project) with per-namespace tool permissions
• Multi-transport — Manage both local stdio processes and remote HTTP/SSE endpoints
• Registry browser — Search the official MCP registry and install servers with pre-populated config
• Interactive TUI — Monitor, test, and manage servers with a terminal interface
• Tool permissions — Block unused tools per-namespace or globally deny dangerous tools at the server level
• Defense-in-depth — Server-level global deny list that overrides all namespace permissions
• Resource & prompt passthrough — Optionally expose upstream resources and prompts via --resources and --prompts flags
• Metadata-faithful — Tool annotations, output schemas, and result structuredContent survive the proxy hop, so readOnlyHint-based auto-approve keeps working

TUI

Web

Installation

Homebrew (macOS/Linux)

brew tap Bigsy/tap
brew install mcpmu

From source

go install github.com/Bigsy/mcpmu/cmd/mcpmu@latest

Quick Start

Let your agent set it up

Install the mcpmu skill, then ask your coding agent to do the rest — it can read your existing MCP config, import your servers into mcpmu, and register mcpmu as your single MCP endpoint:

mcpmu skill install

Then tell your agent: "Read my current MCP config, add all my servers to mcpmu, and register mcpmu as an MCP server"

Or set it up manually with via the TUI, Web or Cmdline

1. Add your MCP servers:

# Start TUI
mcpmu

# Start web
mcpmu web

#Or just use the cli

# Add a stdio server
mcpmu add context7 -- npx -y @upstash/context7-mcp

# Add an HTTP server
mcpmu add atlassian https://mcp.atlassian.com/mcp --scopes read,write

# Add an HTTP server fronted by Cloudflare Access (custom headers on every request)
mcpmu add searxng https://searxng-mcp.example.com/mcp \
  --header "CF-Access-Client-Id: <id>" \
  --env-header "CF-Access-Client-Secret: CF_ACCESS_CLIENT_SECRET"

2. Register mcpmu with your agent:

# Claude Code
claude mcp add mcpmu -- mcpmu serve --stdio

# Codex
codex mcp add mcpmu -- mcpmu serve --stdio

Or add directly to any MCP config JSON (Claude Code, Cursor, Windsurf, etc.):

{
  "mcpmu": {
    "command": "mcpmu",
    "args": ["serve", "--stdio"]
  }
}

That's it. Your agent now has access to all your configured MCP servers through a single endpoint.

Namespaces

Namespaces let you create different server profiles — one for work, one for personal projects, a minimal one for keeping context length down.

# Create namespaces
mcpmu namespace add work --description "Work servers"
mcpmu namespace add personal --description "Personal projects"

# Assign servers to namespaces
mcpmu namespace assign work atlassian
mcpmu namespace assign work context7
mcpmu namespace assign personal context7

Then point each agent at the namespace it needs:

Claude Code:

claude mcp add work -- mcpmu serve --stdio --namespace work

Codex:

codex mcp add personal -- mcpmu serve --stdio --namespace personal

If no namespace is specified, mcpmu uses the default namespace (usually the first namespace created).

Tool Permissions

Control which tools are exposed per namespace — useful for keeping context lean or restricting access. Can also be all configured from the TUI (probably easier there):

# Allow/deny specific tools
mcpmu permission set work atlassian jira_search allow
mcpmu permission set work atlassian confluence_delete deny

# Deny all tools by default, then allowlist what you need
mcpmu namespace set-deny-default minimal true
mcpmu permission set minimal context7 resolve allow

# Per-server deny-default — deny a tool-heavy server, allow the rest
mcpmu permission set-server-default work grafana deny
mcpmu permission set work grafana query_loki_logs allow

Server-level global deny

For defense-in-depth, you can deny tools at the server level. Globally denied tools are blocked regardless of namespace permissions — even a namespace explicit allow cannot override a server global deny:

mcpmu server deny-tool filesystem delete_file move_file
mcpmu server allow-tool filesystem move_file   # re-enable
mcpmu server denied-tools filesystem           # list denied tools

Permission resolution order: server global deny > explicit tool permission > server default > namespace default > allow.

A common pattern: keep a lean namespace with only your most-used tools for everyday work, and an "extra" namespace with the full suite that you add as a second MCP server when needed.

Features

• Stdio process management — Spawn and supervise local MCP servers (npx, binaries, scripts)
• Process-tree cleanup — Stop wrapper-launched workers with their parent and retain identity-validated crash recovery records
• Streamable HTTP/SSE — Connect to remote MCP endpoints with full SSE support
• MCP aggregation — Expose all managed servers as a single MCP endpoint via mcpmu serve --stdio, or over Streamable HTTP via mcpmu serve --http with one URL per namespace
• Faithful proxying — Tool definitions arrive with title, annotations, outputSchema, icons, and _meta intact, and results keep structuredContent; a tool's readOnlyHint reaches your agent instead of being discarded, so auto-approve still works through mcpmu
• Protocol revisions up to 2025-11-25 — Negotiated per client connection rather than pinned, with cancellation and progressToken progress relayed in both directions
• Shared daemon — Concurrent serve clients share one set of upstream processes by default on Unix
• OAuth support — Full OAuth 2.1 with PKCE, dynamic client registration, token management, and automatic scope discovery
• Hot-reload — Serve mode watches the config file and automatically applies changes without restart
• Lazy or eager startup — Start servers on-demand or pre-start everything with --eager
• Per-server startup bounds — Apply startup_timeout_sec to connection, initialization, and initial discovery
• Registry browser — Search the official MCP server registry from the TUI and install with pre-populated config (a → Official Registry)
• Interactive TUI — Real-time logs, server status, start/stop controls, and namespace switching
• Web UI — Browser-based management via mcpmu web with live log streaming, CRUD operations, and registry browser
• Usage metrics — Per-tool call counts, error rates, and latency collected in serve mode, with an unused-tools view answering "am I actually using all the tools I've assigned?" (web UI Metrics page, or GET /api/metrics for scripting)

Serve Mode

Expose managed servers as a single MCP endpoint:

mcpmu serve --stdio                          # default namespace
mcpmu serve --stdio --namespace work         # specific namespace
mcpmu serve --stdio -n work --eager          # pre-start all servers
mcpmu serve --stdio --expose-manager-tools   # include mcpmu.* management tools
mcpmu serve --stdio --log-level debug        # verbose logging

On Unix, the first serve process for a config starts a detached daemon and becomes a stdio shim; concurrent clients then share the daemon's upstream processes. Any connect, spawn, or identity-handshake failure emits one warning and falls back to embedded serve. Use --isolated for one private embedded client, or set top-level "daemonMode": false as a global kill switch. Windows remains embedded.

The daemon inherits the environment and working directory of its first spawner. Prefer absolute server cwd values and explicit config env entries. Servers are shared by default. Stateful servers such as browser automation, REPLs, and interpreter sessions should opt out per server so each connected agent gets its own instance:

{
  "servers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp"],
      "shared": false
    }
  }
}

Private instances have session-scoped tools, notifications, logs, and manager actions, and are stopped when that serve session disconnects. Shared instances also share authentication sessions and upstream rate limits. Calling mcpmu.servers_stop for a shared server stops it for every client; the next use starts it again. For shared: false, that action affects only the caller. See docs/CLI.md for configuration and diagnostic commands.

HTTP serve mode

mcpmu serve --http exposes the same endpoint over the MCP Streamable HTTP transport (POST + SSE) instead of stdio — one long-running process that any number of HTTP MCP clients can connect to:

mcpmu serve --http                                    # 127.0.0.1:8081
mcpmu serve --http --addr 127.0.0.1:9090              # custom port
mcpmu serve --http --addr 0.0.0.0:8081 --token $TOK   # token mandatory off-loopback
mcpmu serve --http --session-idle-timeout 1h --allow-origin https://myapp.example

Each namespace gets its own URL — one running process, many toolsets:

// Claude Code / any Streamable HTTP MCP client
{
  "mcpmu": {
    "url": "http://127.0.0.1:8081/mcp/work",
    "headers": { "Authorization": "Bearer <token>" }
  }
}

POST /mcp uses the default namespace (same auto-select as stdio); POST /mcp/{namespace} selects that namespace. Sessions idle for longer than --session-idle-timeout (default 30m) are reaped, which is what keeps shared: false servers safe here too — each HTTP session gets its own private instance, so session count is process count.

Security: pass a bearer token via --token or MCPMU_SERVE_TOKEN; loopback binds may run tokenless (the unauthenticated endpoint is then loopback-only, plus an Origin check against browsers). Binding a non-loopback address without a token refuses to start — serve-mode tools/call is arbitrary code execution. TLS termination is out of scope; put a reverse proxy in front for network deployments. --isolated does not combine with --http (there is no daemon to skip; use per-server "shared": false for per-session instances). An HTTP serve running beside stdio clients duplicates shared upstream instances across the two processes — tolerated, but worth knowing.

Shell Completions

Tab-completion for server names, namespace names, and subcommand arguments. If installed via Homebrew:

mcpmu completion zsh > "$(brew --prefix)/share/zsh/site-functions/_mcpmu"

For bash, fish, and PowerShell setup see docs/completions.md.

Full CLI Reference

For the complete list of commands, flags, config schema, and HTTP server fields see docs/CLI.md.

Agent Skill

mcpmu ships with a built-in agent skill that teaches AI coding agents how to use the mcpmu CLI. Install it with a single command:

mcpmu skill install

This auto-detects which agents you have installed and copies the skill to the right locations:

The cross-agent path (~/.agents/) is always created as it's the emerging standard.

To remove the skill from all locations:

mcpmu skill uninstall

Once installed, your agent will automatically know how to use mcpmu commands when you ask about MCP server management.

Building from source

git clone https://github.com/Bigsy/mcpmu.git
cd mcpmu
go build -o mcpmu ./cmd/mcpmu
./mcpmu

Testing

go test ./...
make check            # lint + tests
make test-integration # integration tests