Skip to main content
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+,): MCP Servers UI Or directly in your MCP config file (global: ~/.xum/mcp.jsonc, repo overrides: ./.xum/mcp.jsonc):
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

MCP servers declared in an Agent Plugin’s mcp.json also appear in server listings. Plugin servers are:
  • Disabled by default — globally installed plugins can be enabled for all eligible local workspaces in Settings → MCP, which saves their keys in enabledPluginServers in ~/.xum/mcp.jsonc. Repo plugins are enabled per workspace via the Workspace MCP dialog. Workspace enable/disable overrides take precedence over the global default
  • Read-only definitions — commands and tool allowlists cannot be edited globally, and servers cannot be removed individually. Definitions are never written into mcp.jsonc; only enabled server keys appear in enabledPluginServers, which a managed uninstall clears for that plugin
  • Machine-local enablement — restoring mcp.jsonc from a settings backup clears global plugin enablement; enable the servers again in Settings → MCP
  • Review-gated — a server from a managed plugin (installed in Settings → Plugins) starts only after you review its current definition. After an upgrade to a Xum version with component review, each managed plugin needs one review first. See Component review
  • 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
A remote plugin server can declare OAuth sign-in settings (a client, scopes, an authorization server). Its stored sign-in serves it only when that sign-in used the same client and issuer and requested every scope the plugin requires. A sign-in fails when the server grants only some of the requested scopes: the error names the requested and the granted scopes. Otherwise Settings → MCP shows the server as signed out, and you sign in once more. After an upgrade this can happen once for a plugin that requires scopes: when its stored sign-in recorded no scopes, or when the server returned the granted scopes under other names (for example Microsoft Entra permissions for .default, or Google URL forms of short scope names). The new sign-in records the requested scopes. An older Xum version drops that record when it writes its sign-in store, so after a downgrade and an upgrade it can happen once more. 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[/path/to/plugin][@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. With a monorepo subpath (for example cursor/plugins/pstack; for a full git URL, enter the folder in the Plugin folder field), Xum downloads only that folder’s files (a sparse, partial clone) and installs it as the plugin, and the consent preview and update reviews cover only that folder: an upstream commit that changes only files outside it still shows as an update, but applies without a new review. 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. An update also signs out of a remote server whose sign-in settings change or that the update removes. Uninstalling removes the directory, the registry entry, the plugin’s global enablement and per-workspace server overrides, and the stored sign-in of each remote MCP server it declares, but keeps ~/.xum/plugin-data/ unless you opt in to deleting it. Stored sign-ins are keyed by server URL, so another server at the same URL is signed out too.

Plugin server environment

Stdio plugin servers do not inherit your shell environment. Tokens such as GITHUB_TOKEN that you exported for other tools are not passed to a plugin server. Servers that you configure yourself in mcp.jsonc keep your full environment. This is not a sandbox. A plugin server runs as your OS user, so it can still read what your user can read, including the environment of the Xum process on Linux (/proc/<pid>/environ) and credential files in your home directory. Enable only plugin servers that you trust. A plugin stdio server receives only these variables:
  1. The variables its MCP configuration sets in env, plus PLUGIN_ROOT and PLUGIN_DATA.
  2. The host variables a Codex .mcp.json server names in env_vars, when they are set on the host. The consent preview lists these names, and adding a name needs a new review. The review warns about names that change how the server loads code, such as LD_PRELOAD, NODE_OPTIONS and BASH_ENV. A value in env wins over a host variable with the same name. On Windows, Xum compares these names without case.
  3. These host variables, when they are set: HOME, LOGNAME, PATH, SHELL, USER, LANG, LC_ALL, TERM, TMPDIR, TZ and __CF_USER_TEXT_ENCODING. On Windows, the core system variables (PATH, PATHEXT, SYSTEMROOT, USERPROFILE, APPDATA, LOCALAPPDATA, TEMP, TMP and similar) and HOME.
  4. CA bundle paths: SSL_CERT_FILE, SSL_CERT_DIR, REQUESTS_CA_BUNDLE, CURL_CA_BUNDLE, NODE_EXTRA_CA_CERTS, GIT_SSL_CAINFO, CARGO_HTTP_CAINFO, PIP_CERT, BUNDLE_SSL_CA_CERT, npm_config_cafile and NPM_CONFIG_CAFILE.
  5. Variables that Xum sets for every command it runs, so that tools do not wait for input: GIT_EDITOR, GIT_SEQUENCE_EDITOR, EDITOR and VISUAL set to true, and GIT_TERMINAL_PROMPT set to 0. These values replace the same names in the plugin’s env.
Xum also removes these names from every command it runs, even when the plugin’s env sets them: AGENT_BROWSER_SESSION, AGENT_BROWSER_STREAM_PORT, XUM_VENDORED_BIN_DIR, MUX_VENDORED_BIN_DIR and CHROME_DESKTOP. It also removes Xum’s own bin directory from PATH. Xum does not pass any other variable. This includes proxy variables (HTTP_PROXY, HTTPS_PROXY, NO_PROXY, ALL_PROXY), because a proxy URL can contain a password. It also includes package-manager and version-manager variables such as NVM_DIR, VOLTA_HOME, npm_config_registry, UV_* and XDG_CACHE_HOME. A plugin server that starts through npx or uvx behind a proxy, or that needs a token, fails until it gets the variable another way. To give a plugin server another variable:
  1. The plugin publisher sets a fixed value in the server’s env, or, in a Codex .mcp.json, names a host variable in env_vars so that its value is passed from your environment.
  2. You cannot add a variable to a plugin server from Xum settings. Xum has no per-server environment override for plugin servers. Local edits to a managed plugin are lost on the next update.
  3. If you need a variable now, configure the same command as your own server in mcp.jsonc. Your own servers inherit your full environment.

Cursor plugin servers

A Cursor plugin declares its servers in mcp.json at its root, or in the file that the manifest’s mcpServers field names inside the plugin. Without that field, Xum does not fall back to .mcp.json. Xum does not apply an inline mcpServers object.
  • Transport: type: "http", or a url without type, connects over streamable HTTP. type: "sse" stays SSE. A command starts a stdio server.
  • Plugin folder: ${CURSOR_PLUGIN_ROOT} and ${CLAUDE_PLUGIN_ROOT} become the plugin’s install folder in args, env and cwd, as ${PLUGIN_ROOT} does. ${PLUGIN_DATA} works too. A command can be ${CURSOR_PLUGIN_ROOT}/<path> or ${CLAUDE_PLUGIN_ROOT}/<path>. A stdio server also gets CURSOR_PLUGIN_ROOT and CLAUDE_PLUGIN_ROOT in its environment.
  • Values: any other ${...} placeholder, for example ${API_KEY}, ${API_KEY:-default} or ${env:API_KEY}, asks for a value that Xum cannot supply. Xum skips that server and lists it as “needs values not supported in Xum (${API_KEY})”. For the env: form the reason names ${env:API_KEY}. Xum does not read the value from your environment and does not use the default. The check covers command, args, env, cwd, url and headers. Xum has no Cursor data folder, so ${CURSOR_PLUGIN_DATA} and ${CLAUDE_PLUGIN_DATA} count as values too, in a cwd as well.
  • auth: Xum does not apply a Cursor auth block and lists “auth not applied in Xum”. The server still loads. Sign-in uses OAuth discovery and dynamic client registration, not the client in the auth block.
  • placement: Xum lists “placement not applied in Xum” and connects to the server directly.
The install preview and the update review show each skipped server as a warning. The Not applied in Xum list also names each server that needs values, with its reason. A skipped server never appears in Settings → MCP. A remote server with fixed headers does not load in any plugin format. The preview shows that as a warning only. Tool search is on by default. Xum keeps MCP tool definitions out of the model-visible tool list until the model finds them with the tool_catalog_search tool, which saves context when you have many MCP tools. Turn it off in Settings → MCP to advertise every MCP tool up front. Claude 4.5 and later models with Anthropic prompt caching, used directly or through a Coder instance, use Anthropic’s native deferred loading: every MCP tool stays in the request, so the cached prefix is unchanged, and a search loads the matched definitions in place. Other models, including Claude through OpenRouter, GitHub Copilot, or Bedrock, get a tool list that grows as searches find tools. Each search costs an extra model round trip, so the native path defers only when the MCP tool definitions are large (roughly 8k tokens or more); smaller catalogs are sent in full, as with tool search off. On the other models, turning tool search off can be cheaper with only a few MCP tools.

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

Example: GitHub tools

Xum has no built-in GitHub tools. To let agents search code, read files, and work with issues and pull requests on GitHub, add GitHub’s own GitHub MCP server. Its local form runs in Docker and reads a personal access token from the GITHUB_PERSONAL_ACCESS_TOKEN environment variable. This example reads the token from a file when the server starts, so only the server process gets it:
  1. Install Docker and keep it running.
  2. Create a token with only the permissions you want agents to have.
  3. Save the token in ~/.config/github-mcp/token where the server starts, and make the file readable only by you (chmod 600). For a local or worktree workspace, that is the Xum host. For an SSH, Docker, devcontainer, or Coder workspace, the server runs in the workspace, so the file must be there.
  4. Check that the server starts. For a local workspace, use Test in Settings → MCP. Test always runs the server on the Xum host, so for a remote workspace run the command in that workspace’s terminal instead.
CAUTION: Do not put the token in mcp.jsonc, and do not export it in the environment that Xum starts with. Agent bash commands inherit Xum’s environment, so a command that a prompt injection asks for could read an exported token. Agent commands run as your OS user and can also read the token file, so give the token only the permissions you accept an agent to use. The GitHub MCP server’s README lists its other install forms, including a remote server hosted by GitHub, and its toolset options.

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
  4. Use the final URL of a remote server — Xum follows a redirect of a remote MCP server only when it stays on the same origin (scheme, host and port) and keeps the request method (a 307 or 308, or any redirect of a GET). http to https on the same host also works when neither URL has a port. Any other redirect fails with Redirect to <url> not followed, so your headers never reach a host you did not configure. Put that URL in the server config.

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