> ## Documentation Index
> Fetch the complete documentation index at: https://mux.coder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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+,`):

<img src="https://mintcdn.com/mux/MhkqXRaAVwsENfzr/img/mcp-servers-1.webp?fit=max&auto=format&n=MhkqXRaAVwsENfzr&q=85&s=50e5a1c8aad55b6a14231553811ef457" alt="MCP Servers UI" width="2466" height="1880" data-path="img/mcp-servers-1.webp" />

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

```jsonc theme={null}
{
  "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](https://mcp.so/) or the [MCP servers repository](https://github.com/modelcontextprotocol/servers).

## 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