mcpmu

name	mcpmu
description	Install, set up, and manage MCP servers using the mcpmu CLI. Use when the user wants to install mcpmu, register it as an MCP server, add/remove/list MCP servers, manage namespaces, set tool permissions, or expose servers via serve mode.
allowed-tools	Bash(mcpmu *), Bash(brew *), Bash(go install *), Bash(claude mcp *), Bash(codex mcp *), Bash(which mcpmu), Bash(command -v mcpmu)

mcpmu — MCP Server Manager

mcpmu is a multiplexing MCP server manager. You configure MCP servers once in mcpmu, then expose them as a single unified MCP endpoint to any agent (Claude Code, Codex, Cursor, Windsurf, etc.).

Installing mcpmu

First check if mcpmu is already installed:

which mcpmu

If not installed, install via Homebrew (preferred) or Go:

Homebrew (macOS/Linux):

brew tap Bigsy/tap && brew install mcpmu

From source (requires Go):

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

Registering mcpmu as an MCP Server

After installing mcpmu, register it so your agent can use all mcpmu-managed servers through a single endpoint.

Claude Code:

claude mcp add mcpmu -- mcpmu serve --stdio

Codex:

codex mcp add mcpmu -- mcpmu serve --stdio

Any MCP config JSON (Cursor, Windsurf, etc.):

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

With a specific namespace:

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

With management tools (lets the agent add/remove servers via MCP):

claude mcp add mcpmu -- mcpmu serve --stdio --expose-manager-tools

You can verify the registration:

claude mcp list
codex mcp list

To remove mcpmu from an agent:

claude mcp remove mcpmu
codex mcp remove mcpmu

Scoped registration (Claude Code)

Claude Code supports different scopes for MCP server registration:

claude mcp add mcpmu --scope user -- mcpmu serve --stdio       # available in all projects
claude mcp add mcpmu --scope project -- mcpmu serve --stdio    # this project only

Full Setup Walkthrough

To go from zero to a working mcpmu setup:

1. Install mcpmu: brew tap Bigsy/tap && brew install mcpmu
2. Add some MCP servers: mcpmu add context7 -- npx -y @upstash/context7-mcp
3. Optionally create a namespace: mcpmu namespace add work --description "Work tools"
4. Assign servers to it: mcpmu namespace assign work context7
5. Register with your agent:
   • Claude Code: claude mcp add mcpmu -- mcpmu serve --stdio
   • Codex: codex mcp add mcpmu -- mcpmu serve --stdio
   • Others: add the JSON config entry shown above
6. Restart your agent — all mcpmu-managed tools are now available

Adding Servers

Stdio servers (local processes)

mcpmu add <name> -- <command> [args...]

Examples:

mcpmu add context7 -- npx -y @upstash/context7-mcp
mcpmu add filesystem -- npx -y @modelcontextprotocol/server-filesystem /tmp
mcpmu add my-server --env FOO=bar --cwd /path -- ./server --flag
mcpmu add auto-server --autostart -- ./server  # start on app launch

HTTP servers (remote endpoints)

mcpmu add <name> <url> [flags]

Examples:

mcpmu add atlassian https://mcp.atlassian.com/mcp --scopes read,write
mcpmu add figma https://mcp.figma.com/mcp --bearer-env FIGMA_TOKEN
mcpmu add slack https://mcp.slack.com/mcp --oauth-client-id 1601185624273.8899143856786 --oauth-callback-port 3118  # scopes auto-discovered

Flags for HTTP servers:

• --scopes — OAuth scopes (comma-separated; auto-discovered from server if omitted)
• --bearer-env — env var containing bearer token
• --oauth-client-id — pre-registered OAuth client ID (skips dynamic registration)
• --oauth-callback-port — OAuth callback port (1-65535)

Note: --bearer-env and OAuth flags (--oauth-client-id, --scopes, --oauth-callback-port) are mutually exclusive. Note: Most OAuth servers advertise supported scopes via metadata — --scopes is only needed when the server doesn't or you want to restrict the requested set.

OAuth login (for HTTP servers that need it)

mcpmu mcp login <server>
mcpmu mcp login atlassian --scopes read,write
mcpmu mcp login slack  # uses pre-registered client ID from config
mcpmu mcp logout <server>

Listing and Managing Servers

mcpmu list              # human-readable list
mcpmu list --json       # JSON output
mcpmu remove <name>     # remove (prompts for confirmation)
mcpmu remove <name> --yes  # skip confirmation
mcpmu rename <old> <new>   # rename (updates namespace/permission refs)

Namespaces

Namespaces group servers into profiles — e.g. work, personal, minimal. The namespace subcommand can also be shortened to ns.

mcpmu namespace add <name> --description "desc"
mcpmu namespace list [--json]
mcpmu namespace remove <name> [--yes]
mcpmu namespace assign <namespace> <server>
mcpmu namespace unassign <namespace> <server>
mcpmu namespace default <name>
mcpmu namespace rename <old> <new>
mcpmu namespace set-deny-default <namespace> <true|false>

Common namespace patterns

Create separate profiles:

mcpmu namespace add work --description "Work servers"
mcpmu namespace add personal --description "Personal projects"
mcpmu namespace assign work atlassian
mcpmu namespace assign work context7
mcpmu namespace assign personal context7

Create a minimal namespace that denies all tools by default, then allowlist:

mcpmu namespace add minimal --description "Lean toolset"
mcpmu namespace set-deny-default minimal true
mcpmu permission set minimal context7 resolve allow

Tool Permissions

Control which tools each server exposes per namespace:

mcpmu permission list <namespace> [--json]
mcpmu permission set <namespace> <server> <tool> <allow|deny>
mcpmu permission unset <namespace> <server> <tool>

Examples:

mcpmu permission set work atlassian jira_search allow
mcpmu permission set work atlassian confluence_delete deny

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

Flags:

• -n, --namespace — namespace to expose
• --eager — pre-start all servers (default: lazy/on-demand)
• --expose-manager-tools — include mcpmu.* tools in tools/list
• -l, --log-level — debug, info, warn, error

Connecting mcpmu to Other Agents

For Claude Code registration, see "Registering mcpmu as an MCP Server" above.

For other agents:

Codex:

codex mcp add mcpmu -- mcpmu serve --stdio

Any MCP config JSON (Cursor, Windsurf, etc.):

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

For a namespace-specific entry:

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

Interactive TUI

Run mcpmu with no arguments to open the terminal UI for visual server management, log monitoring, and namespace switching.

Config

Config lives at ~/.config/mcpmu/config.json. All commands support --config / -c to use a custom config path.

Shell Completions

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

# bash
mcpmu completion bash > /etc/bash_completion.d/mcpmu

# fish
mcpmu completion fish > ~/.config/fish/completions/mcpmu.fish