MCP integration

PreviewWindowsShips in the preview channel only. Not a stable release.

Harmony as an MCP server: 30+ tools handed to every agent you run, surgical registration, and the first-party trust model.

Harmony registers itself as an MCP (Model Context Protocol) server with Claude, Codex, and Gemini. From that moment, every agent you run arrives already knowing how to drive the machine: your workspace, terminals, browser, and orchestration layer are its tools.

What agents get

30+ tools across nine categories:

Category	Examples
Workspace management	list, create, focus workspaces
Surface lifecycle	create/close terminals, browsers, editors, diffs
Pane management	list, search, get/set metadata
Terminal I/O	send text, send keys, read screen, read events
Browser automation	open, navigate, screenshot (Playwright engine with 30+ tools of its own)
A2A messaging	`nala_agent_send`, `nala_agent_ask`, `nala_agent_reply`, `nala_agent_inbox`
Orchestration	tasks, agents, artifacts, claims, worktrees
Review pipeline	request reviews, resolve findings
Permission bridge	request and resolve permissions

And nala_spawn_propose, the approval-gated way for an agent to ask for another agent.

Surgical registration

Registration is deliberately polite:

Harmony only writes to agent config files that already exist.
TOML-safe edits preserve your comments and ordering.
It never clobbers your own notify programs or unrelated settings.
Codex resume-capture registers a notify bridge so session resume bindings are captured automatically.

Check or manage registration yourself (both shims work; prefer nala):

nala mcp check        # are nala MCP servers registered?
nala mcp register     # add nala entries to agent config files that already exist
nala mcp unregister   # remove them

# Legacy alias still works:
wmux mcp check
wmux mcp register
wmux mcp unregister

First-time setup after install:

Install and authenticate the agent CLI you use (connect a provider).
Run nala mcp register so that CLI receives Harmony's workspace tools.
Restart the agent CLI (or open a new pane) so it reloads MCP config.
Confirm with nala mcp check.

Registration only edits config files that already exist and does not overwrite your unrelated settings.

How the server knows who it is

The MCP server resolves its workspace identity through a ladder: a PID-map walk (unforgeable for its own process tree, since the PTY manager records shell PID to workspace mappings), then a server-side walk from the caller-asserted PID, then environment hints as weak fallbacks. Attribution is best-effort for same-user processes, and anything that cannot be attributed falls through to normal enforcement.

First-party trust, scoped

The bundled server is recognized by name (claude-code, codex-mcp-client) and granted a scoped method allowlist: exactly the RPC methods it invokes, nothing more. Methods outside the set fall through to normal enforcement, and an explicit user denied always wins. This is a convenience, not a backdoor.

The practical effect

With MCP registered, a Claude Code session in a Harmony pane can open terminals, run builds in another pane, drive a browser, post to a channel, and file its own review requests, all through tools Harmony exposes, all journaled by the daemon. Your agents do not just type; they operate the machine the way you would, within the permissions you gave them.