> ## 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.

# murmur mcp — start the Murmur MCP server

> Start the Murmur MCP server so editors and coding agents can call murmur tools to spawn agents, send follow-ups, and inspect status.

Starts the Murmur MCP server, a stdio-based [JSON-RPC 2.0](https://www.jsonrpc.org/specification) server that exposes [agent](/concepts/agents) operations as tools to Claude Code via the [Model Context Protocol](https://modelcontextprotocol.io/). This is the primary interface for agent-to-agent orchestration — spawning child [agents](/concepts/agents), monitoring progress, managing tasks, and receiving real-time events.

On [agent](/concepts/agents) VMs, `murmur mcp` is auto-configured at boot. [`murmur setup`](/cli/setup) registers it for you on local machines when you accept the MCP prompt. To register it manually, run:

```bash theme={null}
claude mcp add murmur murmur mcp
```

## Synopsis

```bash theme={null}
murmur mcp [flags]
```

## Arguments

| Name          | Type   | Required | Description                                                                     |
| ------------- | ------ | -------- | ------------------------------------------------------------------------------- |
| `--debug`     | bool   | no       | Log all JSON-RPC stdin/stdout traffic to `~/.murmur/mcp.log`. Default: `false`. |
| `--workspace` | string | no       | [Workspace](/concepts/workspaces) name. Overrides the value from `murmur.yaml`. |

## Behavior

The server reads JSON-RPC requests from stdin and writes responses to stdout. It runs until the input stream closes or the process receives `SIGINT` or `SIGTERM`.

On startup, the server performs a version check against the API and prints any upgrade warnings to stderr — never to stdout, which is reserved for the JSON-RPC transport.

### Real-time events

The MCP server pushes real-time events to the Claude Code session via the `claude/channel` capability. Events include PR comments, CI results, file changes, child [agent](/concepts/agents) lifecycle transitions, and notifications from humans or [director](/concepts/director) agents. Events arrive automatically, no polling is required.

### Tools exposed

The server exposes all [MCP tools](/mcp-server/overview) — including [`spawn`](/mcp-server/spawn), [`status`](/mcp-server/status), [`ls`](/mcp-server/ls), [`kill`](/mcp-server/kill), [`wait`](/mcp-server/wait), [`upload`](/mcp-server/upload), [`task_create`](/mcp-server/task-create), [`task_update`](/mcp-server/task-update), [`task_list`](/mcp-server/task-list), [`task_get`](/mcp-server/task-get), [`port_url`](/mcp-server/port-url), [`agent_url`](/mcp-server/agent-url), [`queue_add`](/mcp-server/queue-add), and [`clear_queue`](/mcp-server/clear-queue).

See the [MCP server overview](/mcp-server/overview) for the full tool list and per-tool references for parameters and response formats.

## Examples

### Start the MCP server

```bash theme={null}
murmur mcp
```

The server begins reading JSON-RPC requests from stdin. In practice, Claude Code launches this process automatically once it has been registered with `claude mcp add`.

### Start with debug logging

```bash theme={null}
murmur mcp --debug
```

All JSON-RPC traffic is appended to `~/.murmur/mcp.log`. Useful for diagnosing tool call failures or unexpected responses.

### Override the workspace

```bash theme={null}
murmur mcp --workspace backend
```

## Errors

| Code                | Meaning                               | What to do                                                         |
| ------------------- | ------------------------------------- | ------------------------------------------------------------------ |
| `UNAUTHENTICATED`   | Identity token is missing or expired. | Run `murmur auth` or check your `murmur.local.yaml` configuration. |
| config load failure | `murmur.yaml` is missing or invalid.  | Ensure your repository has a valid `.murmur/murmur.yaml`.          |

## Related

* [MCP server overview](/mcp-server/overview) — how the MCP server fits into the Murmur architecture and the full list of exposed tools
* [Agents](/concepts/agents) — concept overview
* [`murmur version`](/cli/version) — check client and server versions