MCP Server

codemux mcp is a stdio Model Context Protocol server that wraps Codemux's local socket API. Any MCP-compatible client — Claude Code, a custom agent, the vexis-agent brain runtime — can drive a running Codemux app programmatically: open and close workspaces, spin up worktrees with an agent already running inside, read and write terminals, drive the browser pane, and 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.

How It Ships

The MCP server is built into the codemux binary — there is no separate install. It runs 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.

Setup

vexis-agent

Add Codemux to ~/.vexis/mcp-servers.yaml:

servers:
  - name: codemux
    command: codemux
    args: ["mcp"]

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

vexis-agent mcp refresh
vexis-agent mcp status

vexis-agent mcp status should show codemux wired into both the claude-code and opencode native files with the command resolvable on PATH.

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"]
    }
  }
}

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

Tool Surface

The server exposes 44 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).

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.

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. The server connects to one local Codemux instance over its control socket. It is not a remote/multi-host transport.