MCP Server
codemux mcp (desktop), an authenticated HTTP endpoint for outside assistants, and codemux-remote mcp (headless) — MCP servers that expose Codemux's control plane and native coding threads to any MCP-aware client.
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, and launch, steer, and read Codemux's own Agent Chat threads.
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 three ways in:
| Server | Where it runs | What it controls | When to use |
|---|---|---|---|
codemux mcp | On your desktop, alongside the Codemux app | The Codemux desktop UI — full surface incl. browser pane, panes, settings, automations, and native chat threads | Desktop agent ("ask Claude to open a workspace") |
HTTP MCP (…/mcp) | Served by the desktop's Remote Access listener | Native chat threads, with OAuth and per-assistant access levels you approve | An outside assistant on another app or machine |
codemux-remote mcp | On any Linux host (VPS, home server) where codemux-remote is installed | The headless codemux-remote serve daemon on that host — workspace registry, terminals, app status | Server-side agent ("Telegram bot uses Codemux on my home server") |
All 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 mcpIt 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.
A codemux mcp you configure yourself is a trusted local controller: running on your machine already implies control of the app, so it gets every tool, including native thread control, with no approval step. Settings → MCP Servers → Outside assistants → Local assistant · STDIO shows the exact command to copy.
The copies Codemux starts on its own — the codemux entry it writes into each workspace's .mcp.json, and the server it gives its own in-app agents — are marked as provider connections. Those get the workspace, browser, and other control tools but not native thread control, so an agent Codemux launched can't take over other Codemux threads.
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 Connect or Set up again for a device in Settings → Devices (or push a workspace to a fresh host), Codemux runs this for you so the daemon is ready the moment install completes:
- Uploads
codemux-remoteto~/.local/bin/codemux-remote. - Installs
~/.config/systemd/user/codemux-remote.service, runsloginctl enable-lingerso the daemon survives logout, and starts the unit. - If a workspace was pushed, drops a
.mcp.jsonin that workspace dir so any agent launched there auto-discovers the MCP server. - 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 statusClaude 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.
Outside assistants (HTTP MCP)
An assistant that can't launch a local command — a hosted assistant, or one on another machine — can connect over HTTP instead. Open Settings → MCP Servers → Outside assistants:
- HTTP MCP connections — off by default. It reuses the Remote Access network listener and never starts or exposes it on its own; if that listener is off, the card says so and offers Open Remote Access.
- Copy MCP URL — the endpoint (ending in
/mcp) to add to your assistant. - Public HTTPS origin — optional. Hosted assistants need a reachable HTTPS reverse proxy in front of this listener; saving an origin doesn't set up or verify the proxy. The from-anywhere relay doesn't carry hosted HTTP MCP. Leave it blank for local HTTP only.
Connecting uses OAuth with desktop consent:
- Add the MCP URL in your assistant and start its OAuth connection.
- The request appears under Authorization requests on the desktop, with the client's self-reported name and callback origin. Pick an access level and Approve (or Deny).
- Press Continue in the authorization browser. Access isn't granted until the assistant finishes its token exchange.
| Access | What the assistant can do |
|---|---|
| Read-only (default) | Read workspace state and visible conversations. Can't launch workers, send messages, or change anything. |
| Supervised | Start threads and send messages in supervised permission modes. Approval requests from those threads stay with you in Codemux — the assistant can't approve its own requests. |
| Full access | Run commands and change files with your account's permissions. Not a project-confined sandbox — approve only assistants you trust. |
A grant applies to all Codemux workspaces and visible conversations, not one project. Approved assistants lists each connection with its access level and expiry; Revoke cuts it off, and it needs approval again to reconnect. Access tokens last an hour and there are no refresh tokens, so after that the assistant has to authorize again — which needs another approval on the desktop.
Over HTTP, the catalog is workspace_list plus the native thread tools — not the browser, pane, terminal, or git tools.
Tool Surface
The desktop server exposes 58 control tools, grouped by category, plus the native thread and delegation tools below:
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), workspace_archive (close restorably without touching the files, branch, or worktree), workspace_unarchive (restore an archive entry), and workspace_archive_list (list restorable entries).
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.
Conversation
conversation_search and conversation_read let an agent pull the full source of a conversation handoff it was given, rather than working only from the summary in its prompt. Search first for message ids, then read chronological pages with a cursor. Both return visible prose only — user messages and top-level assistant text; hidden reasoning, raw tool payloads, approval requests, and subagent internals are excluded. They operate on a conversation reference that arrived in an attachment, so an agent can't browse conversations it wasn't handed.
Notify
notify — send a notification into the Codemux notification panel.
Visual replies
html_render — show a finished, self-contained HTML page (a chart, table, diagram, or mockup) inline in the Agent Chat thread, above the agent's reply. The page runs in a sandboxed frame with the user's theme injected as CSS variables, and is capped at 512 KB. Pages only appear in Agent Chat, not in a terminal session.
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.
Native threads
Launch and drive Codemux's own Agent Chat threads — the same sessions you see in the app — rather than terminal agents:
agent_capabilities— the providers, models, effort levels, and permission modes available for a workspace.thread_list,thread_read,thread_status,thread_wait— list a workspace's threads, read their visible prose by cursor, check live status and pending approvals, and wait up to 20 seconds for a run to settle.thread_launch— start a new thread in an existing workspace. A permission mode must be chosen explicitly. It can't create worktrees or pick Hermes profiles.thread_send— send a follow-up, delivered as queue, steer, or interrupt.thread_interrupt,thread_stop— interrupt a turn, or stop the session and its queued work. Neither deletes the thread, pane, history, or files.thread_respond— answer a pending approval (allow_once,allow_always, ordeny).operation_status— check whether a launch or send was accepted. Accepted or queued isn't the same as finished.
Every change takes a client_request_id; retrying the identical request is safe and won't run it twice. Reads return user messages and top-level assistant text only — never hidden reasoning, raw tool payloads, or subagent internals.
These tools are available to a trusted local codemux mcp and, with the access level you granted, to outside assistants. Codemux's own in-app agents don't get them.
Delegation (in-app agents only)
delegation_targets, delegate_remote_task, task_status, and task_cancel let a Claude or Codex chat inside Codemux send a self-contained task to a checkout on an SSH host you've authorized — see Run a task on a host. They're listed by codemux mcp but refuse every call that doesn't come from an actual in-app Claude or Codex session.
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 tools — only the ones that make sense without a UI:
| Tool family | Tools |
|---|---|
| Workspace | workspace_create, workspace_list, workspace_info, workspace_update, workspace_close |
| Worktree | worktree_create |
| Terminal | terminal_spawn, terminal_write, terminal_read, terminal_list, terminal_close |
| Status | app_status |
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 Devices page 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 on the Devices page when you open the app in the morning. See Devices page → Auto-publish from codemux-remote Hosts for the design rationale.
Limitations
- Native thread control has gaps.
thread_launchstarts threads only in existing workspaces — it can't create a worktree (useworktree_createfor a terminal agent) — and Hermes threads can't be launched through it. In-app agents never get the native thread tools. - HTTP MCP needs your own HTTPS for hosted assistants. Codemux serves the endpoint on its Remote Access listener but doesn't set up a public reverse proxy, and the from-anywhere relay doesn't carry it.
- Desktop vs headless platform support. The desktop MCP server ships on Linux and Windows. The
codemux-remote servedaemon and its headless MCP bridge are Unix-only by design; macOS is not a release target yet. - Single running app per binary. Each
codemux mcpconnects to the local Codemux desktop instance; eachcodemux-remote mcpconnects to the localcodemux-remote servedaemon. Cross-host routing is via SSH (or a future optional cloud relay for paid tiers); it is not a built-in network protocol.