Documentation Index
Fetch the complete documentation index at: https://docs.murmur.dev/llms.txt
Use this file to discover all available pages before exploring further.
The Murmur MCP server is a stdio-based JSON-RPC 2.0 server that exposes agent operations as tools to Claude Code. It is the primary interface for agent-to-agent orchestration: spawning child agents, monitoring their progress, managing task checklists, and reacting to real-time events.
What is the MCP server?
The MCP server is started by murmur mcp. It communicates over standard input/output using the Model Context Protocol — the same protocol Claude Code uses to discover and invoke tools from any MCP-compatible server.
On Murmur agent VMs, the MCP server is auto-configured at boot. The Claude Code settings.json is written with the correct mcpServers entry before the agent session starts. No manual setup is required.
{
"mcpServers": {
"murmur": {
"command": "murmur",
"args": ["mcp"],
"env": {}
}
}
}
murmur mcp and makes them available alongside its built-in tools. The agent can then call spawn, status, task_create, and other tools as naturally as it calls Read or Bash.
How agents use it
An agent running on a Murmur VM interacts with the MCP server transparently. From the agent’s perspective, Murmur tools appear alongside all other tools:
- Claude Code starts and reads
settings.json, which lists the murmur MCP server.
- Tool discovery happens automatically — Claude Code queries the MCP server for its tool list.
- Tool invocation happens through normal tool calls. When the agent decides to spawn a child or check status, it calls the appropriate MCP tool.
- Responses are returned as structured JSON, which Claude Code presents to the agent.
Agents do not need to know they are calling an MCP server. The tools are indistinguishable from built-in tools in the agent’s context.
Slug targeting
Every agent has a slug — a short identifier like fix-auth-bug or add-pagination. Slugs are used to target agents in MCP tool calls.
Relative slugs
When an agent references another agent by a simple slug, it is resolved relative to the calling agent’s path:
fix-bug → targets a sibling or child named "fix-bug"
fix-bug/child → targets "child" under "fix-bug"
Absolute slugs
Absolute paths start with / and fully qualify the agent’s location within a workspace and account:
/w/my-workspace/u/jdoe/fix-bug
/w/my-workspace/u/jdoe/fix-bug/child
/w/{workspace}/u/{account}/{slug}
Use absolute slugs when targeting agents outside your own path — for example, when a flight’s pilot agent needs to reference agents belonging to a different developer.
Empty slug
When the slug parameter is omitted or empty, most tools target the calling agent itself. For example, task_list with no slug returns the current agent’s own checklist.
The MCP server exposes 14 tools organized into four categories:
Agent lifecycle
| Tool | Purpose |
|---|
spawn | Create a new agent task with full configuration |
kill | Cancel an agent and its entire subtree |
wait | Block until an agent reaches a target phase |
ls | List agent tasks with optional filters |
status | Query an agent’s current state, PRs, cost, and timeline |
queue_add | Send a follow-up message to a running agent |
clear_queue | Discard all queued follow-ups for an agent |
Task management
| Tool | Purpose |
|---|
task_create | Add an item to an agent’s checklist |
task_update | Update task status, description, or dependencies |
task_list | List all tasks in an agent’s checklist |
task_get | Retrieve a single task by ID |
Utilities
| Tool | Purpose |
|---|
upload | Upload a file to public storage and get an HTTPS URL |
port_url | Get a public tunnel URL for a port on the current VM |
agent_url | Get the dashboard URL for an agent |
Channel events
Beyond request/response tool calls, the MCP server pushes real-time events to the agent via the claude/channel capability. These events arrive as <channel> tags in the agent’s context and require no polling.
Event types
| Event | Trigger | Typical agent response |
|---|
pr_comment | A developer comments on the agent’s PR | Read feedback, address it, push changes |
pr_review | A developer reviews the agent’s PR | Respond to review comments, make requested changes |
ci_result | CI pipeline completes (pass or fail) | If failed, investigate logs and fix; if passed, continue |
child_lifecycle | A child agent changes state (running, task-complete, failed) | Check child status, collect results, handle failures |
progress | A child agent reports progress | Monitor for problems, usually no action needed |
notify | A human or director sends a message | Follow the instructions in the notification |
file_changed | Files on the base branch changed under the agent’s work | Resolve conflicts as described in the event |
<channel type="ci_result" timestamp="2026-05-08T14:22:10Z">
CI check "tests" failed on commit abc1234.
Run `gh run view 12345 --log-failed` to see details.
</channel>
How events flow
- An external system (GitHub, CI, a parent agent) generates an event.
- The Murmur control plane routes the event to the appropriate agent’s session.
- The MCP server injects the event into the Claude Code session via the
claude/channel capability.
- The agent sees the
<channel> tag in its context and reacts accordingly.
Events arrive automatically — agents never need to poll for them. This is how Murmur achieves real-time responsiveness to PR comments, CI results, and orchestration signals.
Running locally
You can run the MCP server on your local machine for development and testing:
This starts the stdio JSON-RPC server. Configure Claude Code to use it by adding to your settings.json:
{
"mcpServers": {
"murmur": {
"command": "murmur",
"args": ["mcp"]
}
}
}
murmur login). You can spawn agents, check status, and manage tasks just as an agent VM would — useful for testing orchestration logic before deploying it.
Local MCP sessions do not receive channel events, since there is no VM-level session channel. Use murmur watch or the dashboard to monitor agent activity when developing locally.
