MCP Servers
Codemux hosts your installed MCP servers and forwards their tools into Agent Chat sessions.
The Model Context Protocol (MCP) lets agents call out to external tool servers — local filesystem access, web search, database connectors, you name it. Codemux occupies both sides of MCP:
- Codemux as MCP server —
codemux mcp(and, for outside assistants, an authenticated HTTP endpoint) exposes Codemux's control-plane and native-thread tools to any MCP-aware client. See MCP Server for the tool surface and setup. - Codemux as MCP host — while the Agent Chat GUI is enabled, Codemux runs the MCP servers you've already configured for Claude / Cursor / Codemux and forwards their tools into your chat sessions automatically.
This page covers the second role.
What Gets Discovered
Codemux scans the supported user and project scopes used by Codemux, Claude Code, Cursor, Codex, and OpenCode:
~/.codemux/mcp.jsonand<project>/.codemux/mcp.json— Codemux-native user and project configs~/.claude.json— Claude Code user entries plus its per-project local entries<project>/.mcp.json— checked-in project scope and Codemux's auto-written workspace config~/.cursor/mcp.jsonand<project>/.cursor/mcp.json— Cursor user and project configs~/.codex/config.toml— Codex user config~/.config/opencode/opencode.json(or.jsonc) and<project>/opencode.json(or.jsonc) — OpenCode user and project configs
A codemux entry in any of these is skipped — Codemux's own server is always on and listed once.
Configs that appear in multiple places under the same server name are deduped by identical command + args + env. You don't get two copies of the same filesystem server just because both Claude and Cursor know about it.
Lifecycle
- Servers spawn lazily, when the first chat session starts, and each runs once — long-running stdio MCP servers stay alive across sessions.
- When you start or resume a chat session, Codemux registers the servers' tools with that provider.
- When you switch to the classic interface, every MCP server child is killed cleanly.
Which providers see your servers
| Provider | How tools arrive | Note |
|---|---|---|
| Claude | Injected through the sidecar | Claude-native sources (~/.claude.json, <project>/.mcp.json) are excluded — the Claude CLI already loads those itself |
| Codex | Registered as Codex dynamic tools | Names are prefixed codemux_mcp__… because Codex reserves mcp__ for its own servers. ~/.codex/config.toml entries are excluded to avoid doubling |
| OpenCode | An authenticated loopback gateway on an ephemeral port | Needs OpenCode 1.18.18 or newer. If attaching fails the session still starts, with a warning |
| Cursor | Not at all | Cursor loads its own ~/.cursor/mcp.json natively. Codemux discovers those files for display, but injects nothing |
In every case a provider's own native config is left to the provider, so a server configured in both places is used once, not twice.
Settings UI
Open Settings → MCP Servers:
- Server list — one row per discovered server with its source (for example Claude · User or OpenCode · Project), status badge (running / failed / disabled), and tool count. Codemux's own server is always on.
- Enable / disable — per server. Toggling a row off stops it; disabled servers stay in your config files but aren't spawned. If starting, stopping, or restarting a server fails, an error toast names the server and gives the reason.
- Tool list modal — click "View tools" to see every tool the server exposes, with its description and JSON schema. Row actions also appear on keyboard focus and on touch screens, not just on hover.
- Outside assistants — a separate card below the list for letting other assistants control Codemux; see MCP Server → Outside assistants.
- Large tool lists — above 80 registered tools, an advisory note appears: "Large tool lists use more context and can make tool selection less reliable — consider disabling servers you rarely use." It is advice, not a limit; nothing is dropped.
The composer's + popup surfaces the same enable/disable controls inline, so you can flip a server on or off without leaving the chat pane.
There is no longer a tool cap. Codemux used to enforce a hard 50-tool ceiling across all servers, with its own built-ins protected first. Those built-ins grew past 50 on their own, which left the user budget permanently at zero — every one of your MCP tools was silently dropped for injection-based providers while Settings still showed the server as enabled and running. The cap is gone: every tool from every enabled server is registered, and the per-server toggle is the only control.
Known Limitations
- Cursor sessions don't see Codemux-hosted servers. Configure them in Cursor's own
~/.cursor/mcp.jsoninstead. - OpenCode needs 1.18.18 or newer for the gateway attach.
- Tool-list pagination isn't followed. Codemux reads only the first page of
tools/listfrom each server, so a server exposing a very large paginated catalog will appear truncated.
Config Format
Codemux accepts the same format Claude Code does:
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/me/projects"],
"env": {}
},
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..."
}
}
}
}Drop this into ~/.codemux/mcp.json and the servers appear in Settings → MCP Servers on next launch.
Codemux as MCP Server
For completeness: anything Codemux can do via CLI is also exposed via MCP. codemux mcp is a stdio server covering browser automation (DOM / coordinates / OS-level input + viewport presets), workspaces and their restorable archive, panes, terminals, git, GitHub issues, presets, automations, notifications, inline HTML pages, and native chat-thread control.
Codemux writes a codemux entry into each workspace's .mcp.json so terminal agents launched there discover it — turn this off with Settings → Auto-configure MCP for workspaces, or rewrite it with Regenerate MCP config in the command palette. For any other client, point it at codemux mcp; see MCP Server → Setup.
Related
- Agent Chat — where MCP tools are consumed at chat time
- Browser Agent Commands — the browser tool surface Codemux exposes via MCP
- CLI — the human equivalent of the same tool surface