Docs · MCP

Let your agent work the canvas.

Mumble’s reasoning isn’t in the app. It runs in your own Claude Code or Codex, over an MCP server that exposes the same engine the app uses. Point an agent at ~/Mumble and it can read transcripts, draw maps and edit them, with every change landing as a small, readable diff.

Developer setup today. The server is a local binary, mumble-mcp, that speaks MCP over stdio. It needs no API key and no network of its own.

How it fits together

The Mumble app and the MCP server are two front doors to one engine. Both change the map only through the same operations, and both read and write the same plain files. Your agent calls the server’s tools and does its thinking with your own AI provider, under your account.

Two ways in

Connect your agent

Add the server to Claude Code, pointed at your workspace:

claude mcp add mumble -- /path/to/mumble-mcp ~/Mumble

Or as a config block, in a project’s .mcp.json or your user settings:

{
  "mcpServers": {
    "mumble": {
      "type": "stdio",
      "command": "/path/to/mumble-mcp",
      "args": [
        "~/Mumble"
      ]
    }
  }
}

~/Mumble works literally there: the server expands ~ itself. claude mcp add connects straight away. A project-scoped .mcp.json is approved on first use, so claude mcp list shows it as pending until you’ve started a session in that folder once.

Workspace, or one capture

The path you pass is a boundary, not a hint. If the folder contains a capture.json, the agent is scoped to that one capture; otherwise it gets the whole workspace.

mumble-mcp ~/Mumble                                   # the whole workspace
mumble-mcp ~/Mumble/2026-08-20-0900-ramp-hq-replatform  # one capture only
mumble-mcp --refine ~/Mumble                          # adds the two refine tools

Scoped to one capture, the other captures are hidden, not just unlisted: paths are resolved inside that folder, so a symlink or .. can’t reach back out. Use it when you’re handing a session to something that shouldn’t read everything else.

The tools

Fifteen in capture mode, listed in the order you reach for them. The rules for using each one well live in the tool descriptions, so you don’t need to repeat them in your prompt.

The refine tools are absent, not just blocked, in capture mode. While a conversation is being captured, the agent supplies the meaning and Mumble’s rules choose the picture; start a separate refine server when someone wants to override that picture.

Errors are values

Tools never throw. A failed call returns what went wrong and what to do next, so the agent corrects itself without the turn ending:

{ "ok": false, "error": "no node bata" }
{ "ok": false, "error": "capture is required; choose one of: 2026-08-20-0900-…, 2026-08-21-1623-new-test, …" }

A worked example

A workspace with one capture, five utterances and no canvas yet:

> Read the transcript for the ramp-hq capture and build me the diagram.

The tool calls that turn made, in order:

list_captures  get_transcript  get_canvas  get_canvas
set_topic  add_nodes  add_edge  add_edge  get_canvas

It reads before it writes. Once there’s something to read, get_canvas returns a digest the model can reason about:

topic: Ramp HQ replatform          view: diagram

discovery  [step]  "Discovery"  when: "through the end of August" → 2026-08-31
  └precedes→ design-system-work  [step]  "Design system work"  when: "overlaps by about two weeks"
    └precedes→ beta-with-three-customers  [step]  "Beta with three customers"  when: "in October" → 2026-10
      └precedes→ ga  [goal]  "GA"  when: "end of November" → 2026-11-30
api-migration  [step]  "API migration"  owner: Maya  flags: risk

5 nodes, 4 edges · 1 heard-not-scheduled

Then a correction:

> In the ramp-hq capture: beta is the twelfth of October, not just some time in October.

       "label": "Beta with three customers",
       "when": {
-        "said": "in October",
-        "resolved": "2026-10",
-        "precision": "month"
+        "said": "the twelfth of October",
+        "resolved": "2026-10-12",
+        "precision": "day"
       },

Three lines changed. Canvas files are serialised deterministically, so an edit shows up as an edit, not a rewrite. A noisy diff means something reordered where it should have edited.

The files

~/Mumble/
└─ 2026-08-20-0900-ramp-hq-replatform/
   ├─ capture.json       ← the transcript. append-only
   ├─ audio.wav          ← never uploaded anywhere
   └─ diagram.canvas     ← the graph: nodes, edges, and where each came from

A .canvas file is JSON with a version, a view, nodes, edges and pins. Node ids are readable slugs derived from labels, like api-migration, and never change. Editing one by hand is fine; the next get_canvas reads it back. Two rules keep it safe:

• Keep the shape. Keys in schema order, arrays sorted by id, two-space indent. The next agent write re-serialises the file anyway.
• Don’t rename an id. An id is an identity; renaming one orphans every edge that names it. A canvas whose references don’t resolve is refused with the reason, rather than quietly drawing less.

There’s no undo tool across calls. Git is the undo: keep the workspace under version control and every change is a commit you can read.

Known limits

• Don’t write to a capture that’s being recorded. The app watches captures opened from the library and picks up your agent’s changes, but not one it’s recording into, and the two versions aren’t merged yet.
• Captures without a view (hand-written ones, say) need view passed on every call. Captures the app recorded name their own.