MCP Servers

Extend agent capabilities with Model Context Protocol servers

MCP (Model Context Protocol) servers provide additional tools to agents. Configure them globally in ~/.mux/mcp.jsonc, with optional repo overrides in ./.mux/mcp.jsonc.

Configuration

You can either configure the servers in the UI (Ctrl+,):

Or directly in your MCP config file (global: ~/.mux/mcp.jsonc, repo overrides: ./.mux/mcp.jsonc):

{
  "servers": {
    // Knowledge graph for persistent memory
    "memory": "npx -y @modelcontextprotocol/server-memory",
    // Browser automation and screenshots
    "chrome": "npx -y chrome-devtools-mcp@latest --headless",
  },
}

Each entry maps a server name to its shell command. The command must start a process that speaks MCP over stdio (NDJSON format).

Managing servers

Manage MCP servers in Settings → MCP (or by editing the config files directly).

Scope

MCP servers have two scopes:

• Configuration is global with optional repo overrides — Global config lives in ~/.mux/mcp.jsonc, with optional repo overrides in ./.mux/mcp.jsonc
• Runtime instances are per-workspace — Each workspace runs its own server processes, so state in one workspace doesn’t affect another

Per-workspace overrides

mux supports per-workspace MCP overrides (enable/disable servers and restrict tool allowlists) without modifying the shared config files (~/.mux/mcp.jsonc / ./.mux/mcp.jsonc).

These overrides are stored in a workspace-local file: .mux/mcp.local.jsonc.

• This file is intended to be gitignored (it contains local-only workspace preferences)
• When Mux writes this file, it also adds it to the workspace’s local git excludes (.git/info/exclude) so it doesn’t get accidentally committed
• Older mux versions stored these overrides in ~/.mux/config.json; mux will migrate them into .mux/mcp.local.jsonc on first use

This means you configure servers once (globally or with repo overrides), but each workspace (branch) gets isolated server instances with independent state.

Agent Plugins servers (experiment)

With the Agent Plugins experiment enabled (Settings → Experiments), MCP servers declared in an Agent Plugin’s mcp.json also appear in server listings. Plugin servers are:

• Disabled by default — enable them per workspace via the Workspace MCP dialog; there is no global enable
• Read-only — they cannot be edited or removed, and are never written into mcp.jsonc
• Trust-gated — servers from a repo’s .mux/plugins / .agents/plugins only appear once the project is trusted
• Host-only — plugin servers are skipped for SSH and devcontainer workspaces
• Branch-following — in a workspace, repo plugin servers load from the workspace’s own checkout (matching skill discovery), while server identities stay stable across worktrees of the same project

Stdio plugin servers launch with the spec’s PLUGIN_ROOT and PLUGIN_DATA environment variables; per-plugin data directories live under ~/.mux/plugin-data/.

Settings → Plugins installs plugins from git into ~/.mux/plugins (paste a git URL or owner/repo[@ref]). Before anything is written, a consent preview lists the plugin’s manifest, every skill, and every MCP server command line. Installs are pinned to the resolved commit; update checks compare the tracked branch or tag against the pinned commit and never auto-apply. Applying an update replaces the plugin directory wholesale — local edits to a managed plugin directory are discarded — and restarts that plugin’s running MCP servers. Uninstalling removes the directory, the registry entry, and the plugin’s per-workspace server overrides, but keeps ~/.mux/plugin-data/ unless you opt in to deleting it.

Behavior

• Hot reload — Config changes apply on your next message (no restart needed)
• Isolated — Server processes run in the workspace directory with its environment
• Lazy start — Servers start when you send your first message in a workspace
• Idle timeout — Servers stop after 10 minutes of inactivity to conserve resources, then restart automatically when needed

Finding MCP Servers

Browse available servers at mcp.so or the MCP servers repository.

Troubleshooting

If a server fails to start:

1. Test the command manually — Run the command in your terminal to verify it works
2. Check dependencies — Ensure required packages are installed (npx -y downloads on first run)
3. Use the Test button — Settings → MCP shows connection errors inline