Skip to main content
MCP (Model Context Protocol) servers provide additional tools to agents. Mux supports two configuration scopes:
  • Global (~/.mux/mcp.jsonc) — shared across all projects on this machine
  • Project (<project>/.mux/mcp.jsonc) — applies to all workspaces created from that project
If the same server name exists in both files, the project definition wins.

​
Configuration

You can configure servers in the UI (Ctrl+,) under Settings → Projects: MCP Servers UI Or directly in JSONC (same schema for both global and project files): 
{
  "servers": {
    // Simple form (stdio)
    "memory": "npx -y @modelcontextprotocol/server-memory",

    // Full form (stdio)
    "chrome": {
      "transport": "stdio",
      "command": "npx -y chrome-devtools-mcp@latest --headless",
      "disabled": false,
    },

    // Remote server (http/sse/auto)
    "my-remote": {
      "transport": "auto",
      "url": "http://127.0.0.1:8080/mcp",
      "headers": {
        // Header values can come from project secrets
        "Authorization": { "secret": "MY_TOKEN" },
      },
    },
  },
}

​
Notes

  • transport can be stdio, http, sse, or auto (auto will try HTTP and fall back to SSE when needed).
  • headers secret references are resolved from project secrets (Settings → Projects → Secrets), even for globally-configured servers.
  • toolAllowlist (optional) restricts which tools from a server are exposed.

​
Workspace runtime status & restarts

Open Workspace MCP Configuration from the workspace header to:
  • see per-server runtime status (running / failed / not started)
  • restart a specific server when it’s misbehaving
Note: restarts are disabled while a stream is active.

​
Slash Commands

Manage project MCP servers directly from chat (these commands modify <project>/.mux/mcp.jsonc):
CommandDescription
/mcp add <name> <command>Add a new MCP server
/mcp remove <name>Remove an MCP server
/mcp edit <name> <command>Update an existing server’s command
Examples: 
/mcp add memory npx -y @modelcontextprotocol/server-memory
/mcp add chrome npx -y chrome-devtools-mcp@latest --headless
/mcp remove github
/mcp edit chrome npx -y chrome-devtools-mcp@latest --headless --isolated

​
Scope

  • Global configuration — ~/.mux/mcp.jsonc
  • Project configuration — <project>/.mux/mcp.jsonc
  • Per-workspace overrides — .mux/mcp.local.jsonc
  • Runtime instances — 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 config files. 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 / per-project, 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. Check the warning message in chat — mux will report MCP server startup failures during message send
  2. Use the Test button — Settings → Projects shows connection errors inline
  3. Restart the server — Open Workspace MCP Configuration and click Restart
  4. Test the command manually — Run the command in your terminal to verify it works
  5. Check dependencies — Ensure required packages are installed (npx -y downloads on first run)