MCP Tools Reference

This page documents every tool exposed by the Murmur MCP server. Each tool is available to Claude Code sessions running on agent VMs or locally via murmur mcp.

spawn

Create a new agent task. If the agent already exists, returns an error — use queue_add to send follow-ups to running agents instead. Use resurrect: true to resume a dead agent, or force_new: true to start fresh.

Parameters

Parameter	Type	Required	Description
`slug`	string	No	Agent task slug (e.g. `fix-auth-bug`). When `flight` is set, defaults to `flight-<name>`.
`description`	string	No	Task description or instructions for the agent. Required for autonomous mode unless `flight` is set.
`purpose`	string	No	One-sentence human-readable summary of the agent’s goal. Displayed in the dashboard. Max 240 characters.
`model`	string	No	Model override (e.g. `claude-opus-4-6`).
`agent`	string	No	Claude Code agent persona (e.g. `programmer`, `architect`).
`backend`	string	No	Code agent backend: `claude` (default) or `codex`.
`reasoning_effort`	string	No	Reasoning effort level. Claude: `low`, `medium`, `high`, `xhigh`, `max`. Codex: `low`, `medium`, `high`, `xhigh`.
`repos`	array	No	Repos to clone with optional branch overrides. Each entry must have `clone_url`.
`session_mode`	string	No	Session mode: `autonomous` (default), `interactive`, or `streaming`.
`completion_check`	string	No	Completion check: `none` (default) or `assessor` (runs completion assessor up to 3x before idling).
`on_idle`	string	No	Idle behavior: `sleep` (default), `terminate`, `terminate_when_prs_resolved`, or `keep_alive`.
`dequeue_strategy`	string	No	Follow-up dequeue strategy: `all` (default, drain all queued follow-ups), `one` (one per turn), or `five` (up to five per turn).
`resurrect`	boolean	No	Resume a completed/killed agent on the same branch with its full conversation history. Requires the same slug.
`force_new`	boolean	No	Start fresh even if a prior session exists.
`fork_from`	string	No	Branch off another agent’s conversation into a new independent agent. The fork gets the parent’s history but diverges from that point.
`tasks`	array	No	Checklist items the agent must complete. Array of strings.
`append_system_prompt`	string	No	Text appended to the agent’s system prompt.
`out`	string	No	Expected output artifact. Short keywords are expanded: `pr` (open a pull request), `push` (push changes, no PR), `respond` (just respond, no code changes). Freeform text is passed through verbatim.
`flight`	string	No	Flight file path relative to `.murmur/flights/` (e.g. `deploy.md`). Reads and executes the flight via a pilot agent.
`flight_inputs`	string	No	Context inputs for the flight, injected into the pilot prompt (JSON object). Only used when `flight` is set.
`each`	string	No	Fanout: path to a file containing one item per line. Spawns one agent per line. Slug and description must contain `{}` which is replaced with each item.
`workspace`	string	No	Workspace name. Required for new spawns (not follow-ups).

Response

Returns the spawned agent’s slug, workspace, and initial status. When using each, returns all spawned slugs.

kill

Cancel an agent task and its entire subtree. All child agents are also terminated.

Parameters

Parameter	Type	Required	Description
`slug`	string	Yes	Agent task slug to kill. Use absolute path to target agents outside your own path.
`workspace`	string	No	Workspace name. Overrides the session default.

Response

Returns confirmation that the agent and its subtree have been cancelled.

wait

Block until an agent reaches a target phase. Useful for synchronizing with child agents.

Parameters

Parameter	Type	Required	Description
`slug`	string	Yes	Agent task slug to wait on.
`phase`	string	No	Phase to wait for (e.g. `task-complete`, `running`, `idle`). Defaults to any phase needing attention.
`workspace`	string	No	Workspace name. Overrides the session default.

Response

Returns the agent’s full status when the target phase is reached, including phase, progress, PRs, and cost.

ls

List agent tasks. Returns slug, phase, VM, progress, and cost for each task.

Parameters

Parameter	Type	Required	Description
`all`	boolean	No	Include completed and failed workflows. Default: `false`.
`developer`	string	No	Filter to a specific developer login, or `*` for all developers. Empty means caller only.
`workspace`	string	No	Workspace name. Overrides the session default.

Response

Returns an array of agent summaries, each containing:

slug — agent identifier
phase — current phase (e.g. running, idle, task-complete)
vm — VM identifier
progress — task completion progress
cost — accumulated cost

status

Query an agent task’s current state, including phase, progress, PRs, and cost.

Parameters

Parameter	Type	Required	Description
`slug`	string	Yes	Agent task slug. Use absolute path for agents outside your path.
`children`	boolean	No	Include child agent statuses in the response. Default: `false`.
`timeline`	array	No	Timeline event types to include. Omit to exclude timeline. Valid types: `phase`, `child`, `taskComplete`, `commit`, `push`, `checks`, `followUp`, `upload`.
`workspace`	string	No	Workspace name. Overrides the session default.

Response

Returns the agent’s full state:

phase — current lifecycle phase
progress — task completion summary
prs — list of open pull requests
cost — accumulated cost breakdown
timeline — ordered list of events (if requested)
children — child agent statuses (if requested)

queue_add

Send a follow-up message to a running agent. The message is queued and delivered when the agent is ready. Returns an error if the agent is not running.

Parameters

Parameter	Type	Required	Description
`slug`	string	Yes	Agent task slug.
`description`	string	Yes	Follow-up message to send to the running agent.
`tasks`	array	No	Checklist items to add to the agent’s task list. Array of strings.
`agent`	string	No	Agent persona override (e.g. `programmer`, `architect`).
`workspace`	string	No	Workspace name. Overrides the session default.

Response

Returns confirmation that the follow-up has been queued for delivery.

clear_queue

Discard all queued follow-ups for an agent without delivering them.

Parameters

Parameter	Type	Required	Description
`slug`	string	No	Agent task slug. Empty means self.
`workspace`	string	No	Workspace name. Overrides the session default.

Response

Returns the number of entries cleared from the queue.

task_create

Create a new task in an agent’s checklist.

Parameters

Parameter	Type	Required	Description
`subject`	string	Yes	Short summary of the task.
`description`	string	No	Detailed task description.
`activate_when`	string	No	Activation condition name. When set, the task is dormant until the condition is met. Valid values: `files_modified`.
`pattern`	string	No	Glob pattern for file matching (e.g. `.go`, `/_test.go`). Only used with `files_modified`.
`slug`	string	No	Agent slug. Empty means self.
`workspace`	string	No	Workspace name. Overrides the session default.

Response

Returns the created task’s task_id, which can be used with task_update and task_get.

Conditional tasks

When activate_when is set to files_modified, the task remains dormant until files matching the pattern glob are modified. This is useful for setting up reactive tasks:

task_create(
  subject: "Run Go tests after modifying Go files",
  activate_when: "files_modified",
  pattern: "**/*.go"
)

task_update

Update an existing task’s status, subject, description, or dependency edges.

Parameters

Parameter	Type	Required	Description
`task_id`	string	Yes	ID of the task to update.
`status`	string	No	New task status (e.g. `pending`, `in_progress`, `done`, `skipped`).
`subject`	string	No	New task subject.
`description`	string	No	New task description.
`add_blocks`	array	No	Task IDs that this task blocks. Array of strings.
`add_blocked_by`	array	No	Task IDs that block this task. Array of strings.
`slug`	string	No	Agent slug. Empty means self.
`workspace`	string	No	Workspace name. Overrides the session default.

Response

Returns the updated task state.

Task dependencies

Use add_blocks and add_blocked_by to express ordering constraints between tasks:

# Task B cannot start until Task A completes
task_update(task_id: "task-b-id", add_blocked_by: ["task-a-id"])

task_list

List all tasks in an agent’s checklist.

Parameters

Parameter	Type	Required	Description
`slug`	string	No	Agent slug. Empty means self.
`workspace`	string	No	Workspace name. Overrides the session default.

Response

Returns an array of all tasks with their IDs, subjects, descriptions, statuses, and dependency edges.

task_get

Get a single task by ID from an agent’s checklist.

Parameters

Parameter	Type	Required	Description
`task_id`	string	Yes	ID of the task to retrieve.
`slug`	string	No	Agent slug. Empty means self.
`workspace`	string	No	Workspace name. Overrides the session default.

Response

Returns the full task object including ID, subject, description, status, and dependency edges.

upload

Upload a file to the public storage bucket. Reads the file from the given path on disk.

Parameters

Parameter	Type	Required	Description
`filename`	string	Yes	File name for the uploaded object (e.g. `diagram.png`).
`path`	string	Yes	Absolute path to the file on disk.
`content_type`	string	No	MIME type (e.g. `image/png`). Inferred from filename if omitted.
`workspace`	string	No	Workspace name. Overrides the session default.

Response

Returns the public HTTPS URL where the file can be accessed.

Usage

The upload tool is commonly used to share screenshots, diagrams, or build artifacts:

upload(filename: "test-results.html", path: "/tmp/test-results.html")
→ https://storage.googleapis.com/murmur-public/tenant/abc123/test-results.html

port_url

Return a public URL that tunnels to a port on the current VM, accessible from the internet. Use this to share links to services running locally on the agent’s VM.

Parameters

Parameter	Type	Required	Description
`port`	number	Yes	TCP port number (e.g. `3000`).

Response

Returns the public HTTPS URL that tunnels to the specified port.

Usage

Useful for sharing dev server previews, documentation sites, or any service an agent is running:

port_url(port: 3000)
→ https://port-3000-abc123.murmur.dev

agent_url

Return the murmur-ui dashboard URL for an agent. Use this to share a direct link to an agent’s detail view in the browser.

Parameters

Parameter	Type	Required	Description
`slug`	string	No	Agent task slug. Empty means self (on VMs). Use an absolute path like `/w/workspace/u/account/slug` to target any agent.
`workspace`	string	No	Workspace name. Overrides the session default.

Response

Returns the full HTTPS URL to the agent’s dashboard page.

Usage

Commonly used to include dashboard links in PR descriptions or messages:

agent_url(slug: "fix-auth-bug")
→ https://app.murmur.dev/w/my-workspace/u/jdoe/fix-auth-bug

Getting Started

Core Concepts

Guides

CLI Reference

MCP Server

Dashboard

Configuration

Security

Catalog Resources

API Reference

Troubleshooting

Documentation Index

​spawn

​Parameters

​Response

​kill

​Parameters

​Response

​wait

​Parameters

​Response

​ls

​Parameters

​Response

​status

​Parameters

​Response

​queue_add

​Parameters

​Response

​clear_queue

​Parameters

​Response

​task_create

​Parameters

​Response

​Conditional tasks

​task_update

​Parameters

​Response

​Task dependencies

​task_list

​Parameters

​Response

​task_get

​Parameters

​Response

​upload

​Parameters

​Response

​Usage

​port_url

​Parameters

​Response

​Usage

​agent_url

​Parameters

​Response

​Usage

spawn

Parameters

Response

kill

Parameters

Response

wait

Parameters

Response

ls

Parameters

Response

status

Parameters

Response

queue_add

Parameters

Response

clear_queue

Parameters

Response

task_create

Parameters

Response

Conditional tasks

task_update

Parameters

Response

Task dependencies

task_list

Parameters

Response

task_get

Parameters

Response

upload

Parameters

Response

Usage

port_url

Parameters

Response

Usage

agent_url

Parameters

Response

Usage