Codemux hosts your installed MCP servers and forwards their tools into Agent Chat sessions.

MCP Servers

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 exposes 57 Codemux control-plane 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, and Cursor:

~/.codemux/mcp.json and <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.json and <project>/.cursor/mcp.json — Cursor user and project configs

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

Each server is spawned once when Agent Chat starts. 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 path, status badge (running / failed / disabled), and tool count.
Enable / disable — per server. Disabled servers stay in your config files but aren't spawned.
Tool list modal — click "View tools" to see every tool the server exposes, with its description and JSON schema.
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.json instead.
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/list from 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. Run codemux mcp and you get 57 tools covering browser automation (DOM / coordinates / OS-level input + viewport presets), workspaces and their restorable archive, panes, terminals, git, GitHub issues, presets, automations, and notifications.

Auto-configure for Claude Code / Claude Desktop:

codemux mcp

This writes the right ~/.claude.json / claude_desktop_config.json entry so Claude can drive Codemux through MCP.

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

MCP Servers

On this page