~/.xum/mcp.jsonc, with optional repo overrides in ./.xum/mcp.jsonc.
Configuration
You can either configure the servers in the UI (Ctrl+,):

~/.xum/mcp.jsonc, repo overrides: ./.xum/mcp.jsonc):
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.jsoncon first use - Legacy project files under
.mux/remain readable when the corresponding.xum/file is absent
Agent Plugins servers
MCP servers declared in an Agent Plugin’smcp.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
enabledPluginServersin~/.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 inenabledPluginServers, which a managed uninstall clears for that plugin - Machine-local enablement — restoring
mcp.jsoncfrom 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/pluginsonly 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
.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 asGITHUB_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:
- The variables its MCP configuration sets in
env, plusPLUGIN_ROOTandPLUGIN_DATA. - The host variables a Codex
.mcp.jsonserver names inenv_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 asLD_PRELOAD,NODE_OPTIONSandBASH_ENV. A value inenvwins over a host variable with the same name. On Windows, Xum compares these names without case. - These host variables, when they are set:
HOME,LOGNAME,PATH,SHELL,USER,LANG,LC_ALL,TERM,TMPDIR,TZand__CF_USER_TEXT_ENCODING. On Windows, the core system variables (PATH,PATHEXT,SYSTEMROOT,USERPROFILE,APPDATA,LOCALAPPDATA,TEMP,TMPand similar) andHOME. - 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_cafileandNPM_CONFIG_CAFILE. - Variables that Xum sets for every command it runs, so that tools do not wait for input:
GIT_EDITOR,GIT_SEQUENCE_EDITOR,EDITORandVISUALset totrue, andGIT_TERMINAL_PROMPTset to0. These values replace the same names in the plugin’senv.
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:
- The plugin publisher sets a fixed value in the server’s
env, or, in a Codex.mcp.json, names a host variable inenv_varsso that its value is passed from your environment. - 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.
- 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 inmcp.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 aurlwithouttype, connects over streamable HTTP.type: "sse"stays SSE. Acommandstarts a stdio server. - Plugin folder:
${CURSOR_PLUGIN_ROOT}and${CLAUDE_PLUGIN_ROOT}become the plugin’s install folder inargs,envandcwd, as${PLUGIN_ROOT}does.${PLUGIN_DATA}works too. Acommandcan be${CURSOR_PLUGIN_ROOT}/<path>or${CLAUDE_PLUGIN_ROOT}/<path>. A stdio server also getsCURSOR_PLUGIN_ROOTandCLAUDE_PLUGIN_ROOTin 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 theenv:form the reason names${env:API_KEY}. Xum does not read the value from your environment and does not use the default. The check coverscommand,args,env,cwd,urlandheaders. Xum has no Cursor data folder, so${CURSOR_PLUGIN_DATA}and${CLAUDE_PLUGIN_DATA}count as values too, in acwdas well. auth: Xum does not apply a Cursorauthblock and lists “auth not applied in Xum”. The server still loads. Sign-in uses OAuth discovery and dynamic client registration, not the client in theauthblock.placement: Xum lists “placement not applied in Xum” and connects to the server directly.
headers does not load in any plugin format. The preview shows that as a warning only.
Tool search
Tool search is on by default. Xum keeps MCP tool definitions out of the model-visible tool list until the model finds them with thetool_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 theGITHUB_PERSONAL_ACCESS_TOKEN environment variable. This example reads the token from a file when the server starts, so only the server process gets it:
- Install Docker and keep it running.
- Create a token with only the permissions you want agents to have.
- Save the token in
~/.config/github-mcp/tokenwhere 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. - 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.
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:- Test the command manually — Run the command in your terminal to verify it works
- Check dependencies — Ensure required packages are installed (
npx -ydownloads on first run) - Use the Test button — Settings → MCP shows connection errors inline
- 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).
httptohttpson the same host also works when neither URL has a port. Any other redirect fails withRedirect 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.
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.