Agents with MCP access should prefer the notes MCP tools over shelling out to the notes CLI. MCP operations avoid quoting issues and support optimistic concurrency.
• keys — list all document keys.
• get — fetch a note by key. Use include_block_ids: true before patching.
• outline — return a compact block outline as {rev, blocks:[{id,index,type,preview}, ...]}. Use this to choose block IDs with context, without aligning a separate block_ids sidecar array against the full document.
• put — replace a full note document. Use for deliberate whole-document rewrites.
• patch — apply a single block-level or metadata change. Prefer block IDs over indexes.
• batch — apply multiple block-level changes atomically. Use if_rev to avoid overwriting concurrent edits.
• table_op — edit JSONHTL table blocks when present.
• reorder — reorder blocks by supplying every current block ID exactly once, with if_rev.
The MCP server intentionally sends only a small bootstrap and concise tool schemas. On every new connection, begin with get(key='README'). Use this note for MCP details and README/mcp-note-editing for safe structural editing.
patch operations: append_block; insert_block; replace_block; delete_block; delete_blocks; patch_meta; insert_before; and insert_after. Prefer block_id to positional indexes and supply if_rev from a prior read.
table_op operations: rename, insert, delete, move, reorder, fill, and replace columns/rows/cells; sort and deduplicate; captions; transpose; and index management. Address the table by block ID where possible. Parameters are exposed in the tool schema; read the target with block IDs before writing.
Read the target note with include_block_ids: true before patching, preserve metadata and links, increment document version when changing content, set updated to the current date, and link any new child note from its parent.
Detailed MCP note-editing workflow and failure modes are in MCP Note Editing Guide. Read it before doing multi-block or structural MCP note edits.
First, the underlying model: the CLI workflow is get → edit the local file with normal file-editing tools → put the whole document back. The cleverness lives in the local editor, and whole-document put is the norm, not a fallback. Structured MCP ops exist only because an agent over MCP has no local file to edit — they approximate file-editing remotely. So whenever you can edit a local file, do that and put; reach for structured ops only when you cannot. The two strategies below are for the remote case.
For any edit that restructures a note (reordering sections, moving links between sections, multi-op reorganisation), do not edit the live note blind. There are two safe approaches — pick per situation; neither is mandated. Design rationale in verb taxonomy.
• Preview (where supported: dry_run / diff) — default to this for routine structural edits. Cheap, no scratch key, no cleanup. Compute the result, eyeball it, then commit.
• Shadow copy (copy → edit copy → check → move back over original) — reach for this when the edit is large, you want a human to inspect the intermediate in the browser, or you want a durable rollback point. Capture the original's revision first and make the move-back conditional on it so a concurrent writer is not clobbered; carry correct metadata (increment version, preserve created/tags, set updated) on the copy; clean up the scratch key afterwards.
Until preview and copy/move ops exist, the actionable rule from the 2026-06-28 incident (see troubleshooting) stands: for reorganisations, reconstruct the whole document and use put rather than a long positional batch of mixed deletes and inserts; do deletions and insertions in separate batches; re-read and check after any structural edit.
See also README/workflow, README/orphaning and README/mcp-note-editing.