MCP Server

Codemux exposes itself as a Model Context Protocol server so any MCP-aware client — Claude Code, a custom agent, the vexis-agent brain runtime — can drive Codemux programmatically: open and close workspaces, spin up worktrees with an agent already running inside, read and write terminals, drive the browser pane, browse GitHub issues.

This is the inverse of MCP Servers, which covers Codemux hosting the MCP servers you've configured for other tools. This page covers Codemux being an MCP server.

There are two flavours:

Both speak the same MCP protocol; the catalogs differ because a headless host has no UI to drive (no panes, no browser).

Desktop: codemux mcp

Built into the codemux binary — no separate install. Run it as a subcommand:

codemux mcp

It speaks JSON-RPC over stdio and connects back to the already-running Codemux desktop app over the local control socket. Codemux must be running for the tools to do anything; without a live app, tool calls return a connection error rather than failing silently.

Headless: codemux-remote mcp (server-side)

codemux-remote ships the same MCP shape for hosts with no desktop UI. Two pieces:

• codemux-remote serve — a long-running daemon that owns a workspace registry, manages PTYs, and exposes its tools over a loopback HTTP endpoint with bearer-token auth (manifest written to ~/.local/share/codemux-remote/manifest.json, mode 0600). One per host.
• codemux-remote mcp — the stdio MCP server an agent CLI launches. It reads the local manifest and bridges agent tool calls to the daemon over HTTP.

Either you push a workspace from a Codemux desktop and Codemux auto-installs everything on the host, or you install the binary directly on the host (e.g. yay -S codemux-bin on Arch) and run the daemon yourself with codemux-remote serve.

Auto-provisioning on install

When you click Install codemux-remote on this host in Settings → Hosts (or push a workspace to a fresh host), Codemux runs this for you so the daemon is ready the moment install completes:

1. Uploads codemux-remote to ~/.local/bin/codemux-remote.
2. Installs ~/.config/systemd/user/codemux-remote.service, runs loginctl enable-linger so the daemon survives logout, and starts the unit.
3. If a workspace was pushed, drops a .mcp.json in that workspace dir so any agent launched there auto-discovers the MCP server.
4. If a workspace was pushed, registers it in the daemon so it shows up in workspace_list.

Every time the daemon starts, it also scans the user's home directory for known agent CLI MCP-config files (~/.claude.json, ~/.vexis/mcp-servers.yaml) and inserts a codemux server entry pointing at codemux-remote mcp. So an agent launched on the host outside any pushed workspace still discovers Codemux — no manual config edits required. The scan is idempotent (no-op if the entry's already correct), atomic (sibling tmpfile + rename, never corrupts a valid config), and skips agent dirs that don't exist on the host.

After this, codemux-remote serve status reports alive: true and any MCP-aware agent on the host can be pointed at codemux-remote mcp.

Setup

Both binaries are stdio servers — agent → binary → tools. The agent doesn't care which one is running; they're configured identically except for the command name.

vexis-agent

Add Codemux to ~/.vexis/mcp-servers.yaml. Use codemux on a desktop machine, codemux-remote on a host without the desktop app:

servers:
  - name: codemux
    command: codemux           # or `codemux-remote` for headless hosts
    args: ["mcp"]

Then propagate into the per-brain native config files and verify:

vexis-agent mcp refresh
vexis-agent mcp status

Claude Code (and other .mcp.json clients)

Add an entry to the workspace's .mcp.json (or your global Claude Code MCP config):

{
  "mcpServers": {
    "codemux": {
      "command": "codemux",
      "args": ["mcp"]
    }
  }
}

Replace codemux with codemux-remote on headless hosts. Auto-provisioning on push writes this file into pushed workspaces for you.

Claude Code picks the server up on the next session. claude mcp list reports its connection status.

Any other MCP client

If your client takes a launch command and args, point it at codemux mcp (desktop) or codemux-remote mcp (headless). The server speaks plain MCP over stdio — no Codemux-specific protocol on top, no special transport. The same shape that works for Claude Code, Codex, Gemini, OpenCode, Cursor, or any custom agent.

Reaching the daemon from off-host

The headless daemon listens on 127.0.0.1 only — it expects the agent and the MCP client to live on the same machine. If you want to control it from somewhere else, that's a transport question (SSH, mesh VPN, your own reverse proxy) and Codemux doesn't take a position; the daemon is just an HTTP+stdio server like anything else.

Tool Surface

The server exposes 52 tools, grouped by category:

Browser

Drive the embedded browser pane: browser_navigate, browser_snapshot, browser_accessibility_snapshot, browser_click, browser_fill, browser_screenshot, browser_console_logs, browser_click_at, browser_type_at, browser_scroll_at, browser_key_press, browser_drag, browser_click_os, browser_type_os, browser_get_styles, browser_wait, browser_evaluate, browser_viewport, browser_viewport_presets. Covers DOM/accessibility snapshots, CSS-selector and coordinate-based interaction, OS-level kernel input for anti-bot pages, JavaScript evaluation, and viewport presets.

Workspace

workspace_list (all open workspaces with IDs, paths, git info), workspace_info (details on the active workspace), workspace_create (new workspace, optionally at a path), workspace_open (focus an existing workspace by id), workspace_close (close a workspace, optionally removing its git worktree).

Worktree

worktree_create — create a git worktree and a Codemux workspace in one atomic call, optionally launching an agent preset inside with a starting prompt. Mirrors the in-app branch-picker "Fork →" flow.

Pane

pane_list (all panes in the active workspace), pane_split_right and pane_split_down (split a pane), pane_close (close a pane by id).

Terminal

terminal_write (write text to a terminal pane's PTY) and terminal_read (read recent PTY output from a pane's scrollback buffer).

Preset

preset_list (the agent presets Codemux knows about, each flagged with whether its command binary resolves on PATH) and preset_apply (apply a preset to an already-open workspace).

Issue

issue_list (GitHub issues for a repo via the gh CLI), issue_get (a single issue by number), issue_link_workspace (attach an issue to a workspace so it shows on the workspace card).

Git

git_status, git_diff, git_stage, git_commit, git_push — the common git operations, run in the active workspace's directory.

Notify

notify — send a notification into the Codemux notification panel.

Status

app_status (app version, control protocol version, socket path, active workspace, focused pane, and a summary of every open workspace) and port_list (dev-server ports Codemux has detected as listening).

Automations

Manage scheduled agent runs: automation_list, automation_get, automation_create, automation_update, automation_delete, automation_pause, automation_resume, and automation_runs (a single automation's run history). A brain can create and tune recurring jobs without the desktop UI.

Example: Spin Up a Worktree and Start an Agent

A brain delegating work to a fresh Codemux worktree needs two calls. First, discover which agent presets are usable on this machine:

preset_list()
  → [
      { preset_id: "builtin-claude", name: "Claude Code", commands_available: true },
      { preset_id: "builtin-codex",  name: "Codex",       commands_available: false },
      ...
    ]

Then create the worktree, workspace, and agent in one atomic call:

worktree_create({
  repo_path: "/home/you/projects/myapp",
  branch: "feature-x",
  agent_preset_id: "builtin-claude",
  initial_prompt: "implement the feature described in issue 42"
})
  → { workspace_id: "workspace-12" }

worktree_create runs git worktree add, hydrates the workspace, spawns the PTY, runs setup scripts, writes .mcp.json, and launches Claude Code with the prompt already injected. The brain can then follow up with terminal_read, app_status, or workspace_info to track progress.

Headless tool surface (codemux-remote mcp)

A subset of the desktop's 52 tools — only the ones that make sense without a UI:

worktree_create on headless runs git worktree add under ~/.codemux/worktrees/<repo>/<branch> and registers the resulting workspace (prune-before-add for idempotency) — use it (not workspace_create) to fork a branch off an existing git repo on the host. For a brand-new project, git init a folder first (via terminal_spawn/terminal_write), then call worktree_create against it. Workspaces it creates pull back to the desktop with their files and git intact, from the workspace's real on-host path.

Headless worktree_create provisions the new worktree the same way the desktop does: gitignored include files (.env and friends, per .codemuxinclude) are copied from the parent repo before the tool returns, the project's setup scripts run in the background with the full CODEMUX_* environment, and a workspace port is allocated. The tool response includes a setup summary ({port, includes_copied, setup_commands, setup_running}); a failing setup script never fails the call. New branches are created from a freshly fetched origin/<base> tip when the remote is reachable, with a graceful offline fallback.

Excluded on headless: browser_*, pane_* (no UI to drive), notify (no notification panel — logs to journald instead), automation_*, preset_*, git_*, issue_* (planned for a later phase — agents can use their CLI's own Bash tool against terminal_spawn for git/files in the meantime).

Workspaces created here auto-publish to your dev devices

A workspace created on the host through workspace_create (or via the equivalent codemux-remote workspace register CLI subcommand) automatically surfaces in every dev device's Workspaces Overview within ~90 seconds — no explicit push from a laptop required. Each signed-in Codemux desktop polls every configured host over SSH every ~60 s, runs codemux-remote workspace list to read the daemon's registry, and republishes new entries to the cloud registry. So an agent can be told overnight "start a workspace on pandora and begin work on issue 42," and you'll see it waiting for you in the overview when you open the app in the morning. See Workspaces Overview → Auto-publish from codemux-remote Hosts for the design rationale.

Limitations

• Agent Chat tools are not exposed yet. The MCP surface drives terminal-based agent presets, not the Agent Chat (Beta) pane. Agent-chat MCP tools are planned for a later phase.
• Linux-first. The MCP server follows Codemux's platform support: Linux is the primary target, Windows is in progress, macOS is deferred.
• Single running app per binary. Each codemux mcp connects to the local Codemux desktop instance; each codemux-remote mcp connects to the local codemux-remote serve daemon. Cross-host routing is via SSH (or a future optional cloud relay for paid tiers); it is not a built-in network protocol.