MCP

The MCP server gives AI agents structured access to your knowledge base. A few tools answer without a running server: exec (fs-direct shell reads straight off the disk — only the backlink and forward-link enrichment needs the server; history comes from the shadow repo on disk), plus config and palette. preview_url resolves from the project's lock files, but treats opening a preview as demand: if no server is running it auto-starts one (under the OK_MCP_AUTOSTART gate).

Every other read tool (search, links, history, etc.) and all write tools route through the Hocuspocus server, which OpenKnowledge auto-starts on the first call that needs it, under the same OK_MCP_AUTOSTART gate. All tools take a cwd (an absolute path inside the target project) that selects which project the call lands on; a globally registered server requires it unless the client advertises exactly one root.

The surface is 21 tools. The four write verbs — write, edit, delete, move — are native CRUD operations polymorphic over a target. write, edit, and delete nest per-target fields inside the address key (write({ document: { path, content } })) and take exactly one target per call: document, folder, template, or skill — plus asset for write and delete, and a documents batch on write that writes several docs in order, each entry carrying its own summary. move takes flat from/to paths and auto-detects a document, folder, or asset, with nested template and skill targets for those two.

To point an MCP client at this server, locally or over a tunnel from another machine, see Connect remote agents.

Tools

Output shape mirrors the input

The write verbs nest their result under the same target key you wrote, mirroring the input: write({ folder }) returns { folder: { ok, path } }, edit({ document }) returns { document: { … } }, and a batch returns { documents: [ … ] }. The preview envelope (previewUrl, previewUrlSource, warning) stays at the top level on write and edit responses; read tools (search, links, exec) attach a route-only previewUrl to each hit or entry instead. conflicts and links nest the same way under their kind.

Advisory warnings

write and edit results may carry a warnings array on the document entry (per entry for a batch); restore_version carries it at the top level. Entries are discriminated by kind. content-divergence and disk-edit-reconciled are write-integrity signals — the stored doc differs from what the call composed, so re-read it before editing further. mermaid-parse-error means the write landed but that fence won't render — fix the fence and re-edit.

delete, move and install on a skill target carry a separate warnings array of plain strings, not kind-discriminated entries. It reports work that did not undo the operation: bookkeeping records the server could not update after the skill itself was already deleted, renamed or moved, and — on a delete — that the directory removed was one an earlier failed move had retained for recovery. The operation succeeded; the warning names what to check or repair.

Instantiating from a template

write accepts a template field on the document target — write({ document: { path, template } }) — that resolves against the cascade of templates available for the target document's parent folder, using the same folder-up walk the Folders and templates page describes. The template body becomes the new document's content; the template's own info block (its name and description) is stripped, so it doesn't bleed onto the document.

content and template are mutually exclusive. With template, position is forced to replace (initial create semantics).

Editing frontmatter

Use edit({ document: { path, frontmatter } }) for frontmatter edits: it applies a top-level merge patch (set or create a key with a value, delete a key by passing null; a nested object replaces that key's whole subtree, and null inside a subtree is rejected). A document body find/replace (edit({ document: { path, find, replace } })) is body-only and refuses patterns that touch frontmatter; write with position: "replace" is the only write mode that includes the ---\n…\n--- block (other positions ignore any frontmatter in the payload). Folders and templates take frontmatter the same way: edit({ folder: { path, frontmatter } }).

Edit summaries

The write tools (write, edit, move, install, checkpoint, restore_version) accept an optional summary describing the intent of the edit, e.g. "Fixed token-refresh race". Summaries appear on the document's timeline so readers can scan recent agent activity.

Cap is 80 characters. Avoid secrets and PII; summaries persist to git history.

Conflict-aware writes

A doc can land in conflict through a Git merge, a pull that collides with a local overlay, or OpenKnowledge's own reconciliation of the editor against disk. Reconciliation covers stale-external-write, which protects an acknowledged edit when another app restores the exact older file version, even with GitHub sync disabled. Every mutating tool (write, edit, delete, move, restore_version, and agent undo) refuses a conflicted doc with an RFC 9457 problem response (409) that names the kind and the strategies that apply to it:

{
  "type": "urn:ok:error:doc-in-conflict",
  "title": "Document is in conflict.",
  "status": 409,
  "detail": "The document is in a conflict state. Call conflicts({ kind: \"content\" }) + resolve_conflict before retrying.",
  "file": "notes/sso.md",
  "conflict": { "kind": "reconcile", "reason": "disk-markers" },
  "resolutionOptions": ["mine", "content", "delete"]
}

A write that first detects the stale file during its final disk flush returns a different 409, urn:ok:error:stale-external-write. The edit reached collaborative state and the recovery snapshot, but the disk write did not happen. Resolve and re-read before retrying, so you don't duplicate an append that already reached ours.

conflict.kind says where the conflict came from, and the kind decides what a resolve does. merge-native is a git merge that left unmerged stages in the index. Resolving one stages your choice with git and commits the merge once no merge-native conflict is left. working-tree is a pull-only overlay collision, pinned to the origin blob it hit. reconcile is OpenKnowledge's own three-way merge of the editor against disk, including protected stale saves; no git object holds those stages, so OpenKnowledge snapshots them when it detects the conflict. Resolving a working-tree or reconcile conflict commits nothing.

A reconcile conflict also carries a reason: merged-with-markers, refused-conflict-markers, refused-no-base, refused-too-large, disk-markers, or stale-external-write. On that last reason the compatibility field conflictKind is stale-external-write. Every other row uses conflictKind: "git".

A write to a document whose file has been deleted returns urn:ok:error:doc-removed (409): the edit reached collaborative state, but the disk write was refused rather than recreating the removed file. This is not retryable — the document is gone. Re-create it with write if you still want the content.

A write whose document path cannot be resolved inside the content directory returns urn:ok:error:path-escape (400): the edit reached collaborative state, but the disk write was refused. This covers a symlink cycle at the document's own path and a link resolving outside the content directory. It is not retryable — repair the path on disk before writing this content again.

A write refused because the document's duplication baseline could not be read at the final disk flush returns urn:ok:error:store-refused (503): the edit reached collaborative state, but the disk write was refused rather than risk persisting duplicated content. The document file was not updated; the server preserves the edited document, with a copy in its recovery buffer unless that buffer is unavailable or unwritable. Retry only after the filesystem fault is repaired.

A whole-document replace attempted while another writer changed the same document in the last few seconds returns urn:ok:error:concurrent-overwrite-refused (409): nothing was written, so there is no partial edit to undo. This is not tracked conflict state, so conflicts() and resolve_conflict do not apply to it. A single-document HTTP response carries retryAfterSeconds alongside a matching Retry-After header, and the write tool appends the same bound to its error text (Retry after 3s.). POST /api/agent-write-batch keeps its 200 success envelope; each refused entry carries the problem type and retryAfterSeconds, while sibling entries are unaffected. Wait that long and repeat the write, or use position: "append" or "prepend", or edit, which are never refused. Peer writers are distinguished by identity. Anyone supplying an agentId or x-ok-connection-id must use a stable value unique to one writer, containing only ASCII [A-Za-z0-9_-] characters and 1–64 characters long. A nonconforming agentId is discarded: POST /api/agent-write-md and POST /api/agent-write-batch then treat the caller as unidentified, while POST /api/lint/fix falls back to the project principal when available. A nonconforming x-ok-connection-id is silently replaced with a minted identity. A POST /api/agent-write-md caller sends its agentId on every write. The MCP write tools declare no agentId field. OpenKnowledge mints an identity per MCP connection unless an MCP Streamable HTTP client forwards a valid x-ok-connection-id while creating the protocol session. Writers that share or reuse an identity share writer attribution, the server-side write session, and undo history, and are not refused against each other; the server does not detect identity collisions. Having an identity records you as a peer, so a replace carrying a different identity is refused for the next few seconds, while your own recent write does not arm the refusal against your follow-up replace. A writer that has no identity of its own is never recorded as a peer, so it never arms the refusal against a later writer. That covers a POST /api/agent-write-md that omits agentId, and a lint fix that both omits agentId and runs on a project with no principal. A caller that sent no agentId is still refused its own replace when a writer that did send one changed the document in the last few seconds, because that caller cannot be shown to be the recorded writer. Two POST /api/agent-write-md callers that both omit agentId are never refused against each other, though a recent change from a connected editor still refuses both of them.

Resolving a conflict

1. conflicts({ kind: "list" }) returns every tracked conflict as { file, detectedAt, conflict, reason?, conflictKind?, docName }. Call it to detect conflicts without waiting for a 409.
2. conflicts({ kind: "content", file }) returns { content: { file, base, ours, theirs, shape, conflict, reason?, conflictKind?, resolutionOptions } }. ours is the live Y.Text when the doc is loaded and marker-free; otherwise it falls back to the stage pinned at detection. For a stale external write, ours is the protected content and theirs is the rejected older save.
3. resolve_conflict({ file, strategy, content? }) writes the chosen bytes. Send a strategy from that conflict's resolutionOptions, not the full set. A reconcile conflict whose theirs side is raw marker text does not offer theirs, and sending it anyway returns a 422 with refusal: "strategy-not-offered". The same 422 shape carries refusal: "markers-in-content" when the bytes you sent still contain markers, and that field is what tells the two apart. A 404 (urn:ok:error:no-conflict-tracked) means nothing is tracked for that path. Re-read the list; it does not mean your resolution was saved.

What mine and theirs mean depends on the kind. On merge-native they are git checkout --ours and git checkout --theirs (the committed stages 2 and 3), and delete is git rm. On working-tree, mine keeps your overlay verbatim and theirs restores the pinned origin blob. On reconcile, mine uses the latest marker-free live Y.Text, falling back to the captured editor stage when the document is unloaded or contains markers; theirs uses the disk bytes captured at detection. content always writes the bytes you supply, and delete always removes the file.

file is a .md or .mdx path relative to the project directory, extension included. It mirrors the on-disk shape, not the extension-less document path the other tools take.

For how a conflict appears and resolves in the app, see Resolving a conflict. The conflicts and resolve_conflict tool descriptions repeat the per-kind rules at the call site.

Preview links

Read and write tools return a previewUrl for any doc they touched, but those are route-only (/#/<doc> with no host:port), meant to identify the doc, not to be opened as-is. Hosts that want to open the editor (Claude Code Desktop's preview_start({url}), terminal open <url>) call preview_url to resolve the full URL once per session.

preview_url always carries an autoOpen boolean (top-level on its response) reflecting the user's appearance.preview.autoOpen preference. The write tools (write, edit) carry the same boolean on the warning object, which fires only when no browser is attached to the preview. In the common case (a browser is attached), the write response has no warning and no autoOpen field. Agents honor autoOpen before navigating: true (default) follows the host-capability routing in the bundled skill; false means the user is managing their own preview window, so the agent surfaces the URL on request but does not open or refresh anything. The value is resolved fresh on every tool call, so a mid-session toggle propagates within 0–1 calls, with no client restart.