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:

1. Codemux as MCP server — codemux mcp exposes 44 Codemux control-plane tools to any MCP-aware client. See MCP Server for the tool surface and setup.
2. Codemux as MCP host — when Agent Chat (Beta) is on, 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 three places coding tools typically store MCP configs:

• ~/.codemux/mcp.json (or ~/.config/codemux/mcp.json) — Codemux-native config
• ~/.claude.json and any project-level .claude/settings.json — Claude Code's MCP config
• ~/.cursor/mcp.json — Cursor's MCP config

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 the SDK via an in-process facade (Claude uses setMcpServers; Codex support is on the roadmap).
• When you flip Beta Features off, every MCP server child is killed cleanly.

Settings UI

Open Settings → MCP:

• 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.
• 50-tool cap warning — agents start to misbehave when given hundreds of tools. Codemux warns when your enabled servers expose more than 50 tools combined; you can ignore the warning, but expect more tool-selection errors.

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.

Codex Support

Codex doesn't yet expose an MCP host API the way Claude SDK does. The plan (Step 11) is for Codemux to ship a localhost streamable HTTP MCP gateway that Codex consumes as a single MCP entry. Codex's config/mcpServer/reload RPC will let registry changes hot-reload without bouncing the session.

Until that ships, MCP tools are live for Claude sessions only. Codex sessions still work — they just don't see your MCP servers.

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 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 31 tools covering browser automation (DOM / coordinates / OS-level input + viewport presets), workspaces, panes, git, and notifications.

Auto-configure for Claude Code / Claude Desktop:

codemux mcp install

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

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