MCP Server

Use the ccmux MCP server to let a coding agent inspect sessions, read project notes, and check usage. Session creation, keystrokes, and termination are available only when you enable mutation.

The server binary is included with ccmux v0.3.0 and later. Install ccmux and make sure its daemon is running before connecting a client.

Wire it up

For Claude Code, register a local stdio server for your user account:

claude mcp add --transport stdio --scope user ccmux -- ccmux-mcp

Run /mcp inside Claude Code to check the connection. See Claude Code’s MCP documentation for configuration scopes and troubleshooting.

For a project-scoped configuration, use .mcp.json at the project root:

{
  "mcpServers": {
    "ccmux": { "command": "ccmux-mcp" }
  }
}

Other MCP clients use their own configuration format. Add a stdio server whose command is ccmux-mcp; use the binary’s absolute path if the client cannot find it on PATH.

The agent now has these tools:

These tools are read-only. They expose information available to the connected daemon.

When you want it to do things

Add --allow-mutate to the server arguments. For a project-scoped Claude Code configuration:

{
  "mcpServers": {
    "ccmux": { "command": "ccmux-mcp", "args": ["--allow-mutate"] }
  }
}

That unlocks:

Off by default for a reason: an agent that can send_keys into your work is an agent that can type anything you can type. The flag is the opt-in. There’s no per-tool override — you turn the whole mutating set on or you leave it off.

Without the flag, mutating tools are absent from tools/list. Restart the MCP server through your client after changing its arguments.

Drive a remote machine

CCMUX_HOST=mini.tail-xxxxx.ts.net:7474 ccmux-mcp
# or
ccmux-mcp --host mini.tail-xxxxx.ts.net:7474

The agent runs locally and queries the daemon on the Mac mini. Mutating tools still require --allow-mutate. Same protocol, same tools — just over Tailscale HTTP instead of the local Unix socket. Useful for “I’m coding on the laptop, but the overnight Claude work is on the mini.”

What this is actually for

A few concrete shapes:

Multi-session orchestration. An agent in one session spawns a helper in another (spawn_session in a different project), reads its output once it’s done (read_pane), pulls the result back, kills the helper. No human in the loop.

Cross-machine work. An agent on your laptop checks how its sibling on the Mac mini is doing (list_sessions, read_pane), without you SSH-ing in. Or starts a long-running build on the mini (spawn_session after configuring the MCP server with --host and --allow-mutate) and continues its local work.

Project memory. An agent reads the project’s notes at the start of a session (list_notes + read_note) so it doesn’t repeat work the previous agent did. The notes are plain markdown on disk; the agent doesn’t need to know that.

Cost awareness. Before kicking off a big run, the agent checks get_usage to see what you’ve spent this week, and get_daemon_health to see how many sessions are already running.

None of this needs new infrastructure. ccmux already had all of it. MCP is just the protocol that makes it agent-accessible.

Security model

• Transport. stdio. The Unix socket the daemon listens on is user-scoped; tailnet HTTP requires being on your tailnet.
• Mutation. Off unless you flip the flag.
• Bounded reads. read_pane caps at 500 lines so a buggy agent can’t drag the daemon down asking for the full scrollback every call.
• Per-call deadline. Every handler runs under a 30-second context.

Current limits

The server provides request/response tools. Live subscriptions, per-tool mutation permissions, and a prompt library are not currently available.

Related guides

• Configure a remote host before targeting its daemon.
• Read the HTTP API reference to build a client directly against ccmuxd.

Spotted an error or something out of date? Edit this page on GitHub.