> ## Documentation Index
> Fetch the complete documentation index at: https://mux-mike-server-self-update.mintlify.site/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 `~/.xum/mcp.jsonc`, with optional repo overrides in `./.xum/mcp.jsonc`.

## Configuration

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

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

Or directly in your MCP config file (global: `~/.xum/mcp.jsonc`, repo overrides: `./.xum/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 `~/.xum/mcp.jsonc`, with optional repo overrides in `./.xum/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

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

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

* This file is intended to be **gitignored** (it contains local-only workspace preferences)
* When Xum 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`; Xum migrates them into `.xum/mcp.local.jsonc` on first use
* Legacy project files under `.mux/` remain readable when the corresponding `.xum/` file is absent

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](https://agent-plugins.org) `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 `.xum/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 `~/.xum/plugin-data/`.

**Settings → Plugins** installs plugins from git into `~/.xum/plugins` (paste a git URL or `owner/repo[@ref]`); the exact location derives from the active Xum home (a legacy `~/.mux` home keeps working) and is shown in the section. 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 `~/.xum/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](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

## Claude Design experiment

Enable **Claude Design MCP** in Settings → Experiments, then configure the
**Claude Design** card in MCP settings. Turning on the experiment alone does not
read credentials or connect.

Choose a credential source on the **Mux backend host** shown in the card:

* On macOS, select the Keychain service and account used by your Claude Code
  installation. The usual service is `Claude Code-credentials`, with your OS
  username as account. Custom Claude configuration directories can change this;
  confirm your installation's values. Keychain reads fail without prompting if
  access is unavailable.
* On macOS, Linux, or Windows, you can explicitly select an absolute credential
  file path. Claude Code installations using plaintext fallback commonly use
  `~/.claude/.credentials.json`; expand the path and confirm it exists on the
  backend host. Mux does not search for files or infer directory overrides.
  POSIX files must belong to the backend user and deny group/other access.
  Windows files must belong to the backend user and grant access only to that
  account, SYSTEM, and administrators.

Select **Use Claude Code credentials** to opt into read-only access and test the
connection. Then enable `claude_design` globally in MCP Servers. Workspace MCP
controls can restrict access, but cannot enable a globally disabled Design server:
checkout-local files are not authoritative consent to use your Claude credentials.
Existing tool allowlists and HTTP MCP policy still apply. A conflicting
server name must be renamed or removed first; Mux never replaces that server or
lends it Claude credentials.

Mux prefers an unexpired `designOauth` access token. It can fall back to an
unexpired `claudeAiOauth` token only when both `user:design:read` and
`user:design:write` are explicitly present. API keys are not a substitute.
Credential storage and token compatibility depend on Claude Code's private
implementation; this is an unsupported compatibility experiment, not an
independent OAuth client.

Claude Code owns login, scope authorization, consent, refresh, and revocation.
When setup is missing, credentials expire, or Design requests consent, complete
that action in Claude Code on the backend host and select **Retry connection**.
Mux does not initiate those flows. On a 401 it rereads storage once and retries
only if the same credential kind now has a different usable token. It never
refreshes or writes Claude tokens, acquires Claude refresh locks, or automatically
replays a failed tool after consent.

All Design HTTP requests originate on the backend host, including for SSH and
container workspaces. A browser connected to a remote Mux backend uses credentials
on that remote backend, not credentials on the browser's computer. Credentials
are never forwarded into workspace processes or returned to the renderer.

**Disconnect** disables reuse and server enablement. Disabling the experiment
also stops its clients and removes its tools from subsequent catalogs. Neither
action logs out Claude Code, revokes consent, or modifies its credential store.
Requests already accepted by Design cannot be undone. Mux stores only source and
enablement preferences in `<config.rootDir>/claude-design.json`, normally under
`~/.xum/`; borrowed tokens are not copied there or into `mcp.jsonc`.

The card supports Ctrl/Cmd+Enter to connect and Ctrl/Cmd+Shift+D to disconnect
while focus is inside the form. Native platform credential access and live Design
compatibility must be verified in your deployment; automated tests use synthetic
credentials and a local MCP server.