Serving over MCP

kli mcp-serve cairn runs a kli built with the cairn extension as a Model Context Protocol server over stdio. The process exposes one extension's surface to a single client: cairn's fourteen tools, seven prompts, and seven readable resources. A client connected this way plans, observes, queries, and resumes against the same durable task graph it would reach inside kli, without adopting kli as its agent.

This page documents the command, its client configuration, and the exact surface it carries. For the install paths behind the kli binary, see Install cairn.

The command

kli mcp-serve cairn

The invocation is kli mcp-serve <extension>, where <extension> is the name of an extension built into the kli image — here, cairn. The process speaks MCP over stdio, reading requests on stdin and writing responses on stdout — the transport every MCP client uses to launch a server. On launch it prints no banner to stdout; stdout carries JSON-RPC only, every diagnostic goes to stderr, and the process blocks waiting for the first request — a clean start goes quiet rather than printing anything. It serves until the client closes the connection.

The working directory the client launches kli in selects the project whose task graph cairn opens. There is no separate database flag; the project is the directory.

Client configuration

Claude Code, Claude Desktop, and Cursor read the same mcpServers block. The canonical entry is:

{
  "mcpServers": {
    "cairn": {
      "command": "kli",
      "args": ["mcp-serve", "cairn"]
    }
  }
}

The client spawns this process, lists its tools, and routes tool calls to it, picking up a newly added entry on its next restart.

Exposed surface

mcp-serve exposes one extension's surface and nothing else. Naming cairn gives the client cairn's surface alone; no other extension's tools, prompts, or resources travel on the same process. The surface is the same regardless of which client connects.

Tools

The fourteen cairn tools appear as MCP tools, each gated by the capability it declares. The full per-tool reference — parameters, return text, and semantics — is in Tools.

The serve subject holds exactly the capabilities its exposed tools declare, so the :cairn/read / :cairn/write / :cairn/observe split applies over MCP just as it does in kli. The capability each tool declares is the gate; the tool name is not. A read-only client never reaches task_query_write or any other write tool. See Reads, writes, and capabilities.

Prompts

Seven MCP prompts travel on the process: the six cairn-method workflow prompts plus the cairn-method skill, which the serve loop lists as a prompt as well as a resource. They carry the documentarian-and-TDD discipline of the cairn-method into the client's prompt picker.

The six workflow prompts are the named loop; see The cairn-method for how they compose. The seventh, cairn-method, is the bundled skill surfaced in the prompt list.

Resources

Every prompt and the skill are also served as readable MCP resources — seven in all, each a markdown body the model reads straight off the prebuilt prompt or skill. The workflow prompts are advertised at cairn://prompts/<name> (for example cairn://prompts/research), and the skill at cairn://skills/cairn-method; the scheme is the extension name. A client that reads the skill resource gets the method in full — the bootstrap-observe-handoff heartbeat and the discipline wrapped around it — as text the model can consult mid-task.

What stays kli-only

Three things kli provides do not travel over the tool protocol, because kli supplies them as the host rather than as MCP surface. A plain MCP client does not get them.

• Slash commands. /observe, /handoff, /task, /tasks, /workon, and /where are registered under a kli command provider, not as MCP tools, so an MCP client cannot invoke them. See Slash commands.
• Per-turn context injection. Inside kli, the current task's live state — its status and its open handoffs — is folded into the model's view on every turn. Over MCP the client calls task_bootstrap itself to stay oriented.
• Compaction folding. When kli compacts a long conversation, the observations and handoffs from the dropped span are folded into the summary so the durable markers survive the cut. An MCP client manages its own context window, and its compaction does not know about those markers.

The data surface is identical either way: writes append events and fold into the same queryable projection no matter which client made them, so a graph built over MCP reads back exactly as one built inside kli.

What a connected server reports

A connected server advertises the fourteen tools listed above, among them task_bootstrap, task_create, observe, task_query, and task_search.

task_bootstrap reads the live graph. In a fresh project with no current task set, it reports that there is nothing to orient on rather than failing:

No task to bootstrap; pass task_id or select a task first.

That message means the tool surface is wired and the project's graph is empty — the state a first session starts from. In a project that already has tasks, task_bootstrap returns state, neighbors, open handoffs, and recent observations. Either result means the server is connected and reading the right project.

Related

• Install cairn — the declarative and runtime install ledgers behind the kli binary.
• Tools — the full per-tool reference for the fourteen exposed tools.
• Reads, writes, and capabilities — the capability boundary that carries over MCP.
• Slash commands — the kli-host steering surface that does not travel over the protocol.