Skip to main content
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+,): MCP Servers UI 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.

​
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