MCP server reference

cdno-mcp is a Model Context Protocol server that exposes your vault to AI clients (Claude Desktop, Claude Code, Kiro, Gemini CLI, …). It runs the same domain engine as the CLI, so anything the assistant does goes through the same rules and lands in the same Markdown files. To wire it up, see Connect to Claude.

Transport and vault selection

Two binaries serve the same tool catalogue:

• cdno-mcp speaks JSON-RPC over stdio — the client launches it as a subprocess. It opens the vault named by CUADERNO_VAULT_PATH, or, if that’s unset, discovers one from its working directory (the same rule as the CLI).
• cdno-mcp-server speaks MCP Streamable HTTP for remote clients — see The HTTP server for its flags and security model.

The tool surface

The server advertises 66 tools. This reference groups them by purpose:

Every tool returns typed JSON; the shapes mirror the CLI’s --json output, so a client gets the same structures whichever surface it uses.

Focus

Four of the write tools (pause_action, switch_action, switch_unplanned_action, resume_action) move the one “what I am on” slot that current_focus reads, and eighteen write results carry a focus field so the focus rides along without a second call. The server never refuses a write for being outside the focus; it refuses a second start (or a switch to the focused action, or a resume_action over a different focus) with a coded focus_open rejection, and pause_action or resume_action with nothing to act on with no_focus. See Write tools and Focus.

Conventions

• Slugs, not paths. Tools take slugs (surrogate-model), matching the CLI.
• Substring matching for completing actions/milestones and resolving waiting-on items, exactly as on the CLI.
• The same rules apply. The five-project cap, append-only notes, auto-logged project-state history, and commitments aggregation all hold — the MCP server is not a back door around them.

When a call is rejected

Cuaderno splits failures along the line MCP itself draws, and the distinction is worth knowing because the two arrive in different places in the response.

A rejection you can act on comes back as a tool result with isError: true — not as a JSON-RPC error. The response carries no error member at all, and the payload is the single text content item, JSON-encoded exactly as a successful result’s payload is:

{ "isError": true, "content": [{ "type": "text", "text": "…" }] }

Decoding that text gives the rejection itself. This is real output from complete_action with a query matching two bullets:

{
  "code": "ambiguous_action",
  "details": {
    "candidates": [
      "Draft the methods section (deep)",
      "Revise the methods appendix (light)"
    ],
    "query": "methods",
    "slug": "ablation-study"
  },
  "message": "ambiguous action match for 'methods' on project 'ablation-study': [\"Draft the methods section (deep)\", \"Revise the methods appendix (light)\"]"
}

Three fields, and each has a job:

details is the part that matters for automation. An ambiguous query hands back its candidates as an array, so a client picks from a list rather than parsing them out of a sentence.

Five project codes carry details a client is likely to branch on:

The test is simply whether a different argument would change the outcome. A slug that matches no note is a rejection (not_found), and its message carries the list of slugs that do exist. A note missing the section a tool writes into is a rejection. So is a name that is already taken.

A mechanical failure stays a JSON-RPC error (-32603): a disk that would not write, permission denied, a contended write lock, an index that would not answer, a transaction that rolled back. Nothing the caller passed can fix those, so there is nothing to branch on. Malformed calls — an unknown tool, unparseable arguments — are protocol errors too (-32602), per the spec.

The practical upshot for a client: read isError on the result, not just the presence of error. A rejection is a normal, expected answer to a call that was itself well-formed.

Slug rejections

An explicit slug on a create tool (Creation and lifecycle) is refused with one of four codes, each leaving the vault untouched. They are the same objects the CLI prints under --json.

Building skills on top

Multi-step rituals (a morning orientation, a guided weekly review) are best wrapped as Claude skills that call these tools in sequence. See Using with Claude skills.