MCP Server

Expose your vault to AI agents as typed Model Context Protocol tools. Claude Desktop, Cursor, or any MCP-aware agent can then search pages, traverse backlinks, resolve Wikilinks, ask for similar pages, and run reasoning queries — without giving up control of the underlying files.

Requires --features mcp at install time. See Installation.

Why

Agents need structured access to your knowledge. Dumping a vault into a context window loses the graph; scraping files on disk loses the reasoning layer. MCP gives the agent a typed tool surface — search, get_page, links, backlinks, path, similar, check, status, reason — backed by the same index zetl uses itself. You stay local-first; the agent never touches your files directly.

Transports

# stdio — for Claude Desktop, Cursor, and any editor that spawns the server
zetl -d ./my-vault mcp

# HTTP — for remote agents, CI bots, shared deployments
zetl -d ./my-vault mcp --transport http --port 3100

--transport stdio is the default. HTTP binds to 127.0.0.1 by default; pass --insecure to allow a non-loopback bind (don’t do this without a reverse proxy and a delegate token — see below). --cors-origin https://agent.example.com scopes the browser-side surface.

The available tools

Tool	What it does
`search`	Full-text search across the vault
`get_page`	Fetch a page by name — Markdown + frontmatter
`links`	List forward links from a page
`backlinks`	List pages pointing at a page
`path`	Shortest path between two pages in the link graph
`similar`	SimHash-nearest pages (see Similar Pages)
`check`	Run `zetl check` — dead links, orphans
`status`	Reasoning conclusions for a page (requires `--features reason`)
`reason`	Evaluate an SPL query (requires `--features reason`)

The reasoning tools exist only when zetl was built with both mcp and reason features — see What is Defeasible Reasoning for what they return.

Delegate tokens

An agent shouldn’t get your unscoped identity. zetl issues user-signed JWTs — delegate tokens — that scope access per-tool and per-page glob:

# All tools, all pages, no expiry (convenient; pair with a short-lived key)
zetl delegate

# Read-only subset
zetl delegate --tools search,get_page,links,backlinks

# Scope to a folder
zetl delegate --scope "projects/**"

# Time-limited
zetl delegate --expiry 7d

# First-time key setup from a BIP39 mnemonic
zetl delegate --mnemonic "word1 word2 ... word12" --save-key

--save-key writes the derived signing key to ~/.config/zetl/identity.key so later delegate runs don’t need the mnemonic. The server verifies tokens against the issuing identity and rejects anything missing the claimed scope or expired. --allowed-issuer <DID> on the mcp command restricts which identities may issue tokens for that server — the right knob for a shared HTTP deployment.

Claude Desktop config

Drop this into claude_desktop_config.json:

{
  "mcpServers": {
    "zetl": {
      "command": "zetl",
      "args": ["-d", "/path/to/vault", "mcp"]
    }
  }
}

Claude Desktop spawns one stdio subprocess per MCP server it knows about, so the agent has live access the whole time the chat is open. Restart Claude Desktop after editing the config. The zetl server logs to stderr — visible in the Desktop log pane if a tool call misbehaves.

Cursor / other IDEs

Any MCP-aware client that takes a command + args pair works the same way. Point the config at the zetl binary with -d <vault> and mcp; the client handles transport. For HTTP clients, configure the token header with the output of zetl delegate.

What the agent sees

Tools are typed. search takes a query string and an optional result limit; get_page takes a page name and returns structured {frontmatter, content, path}. The agent’s tool-use loop can chain calls — search for a term, backlinks on the top result, path between that and a reference note — without ever seeing a raw filesystem path it could mis-interpret.

Writes are not exposed. The MCP surface is read-only. Agents that need to create pages should use the zetl serve API, which has proper auth and CRDT-aware saves.

Lifecycle Hooks — the on-agent hook fires on every MCP tool call; use it for audit logging.
Running a Team Server — sharing a vault across users; MCP plays well with the same collab identity keys.
Capability URLs — the static-site analogue for sharing without a running server.
Installation — cargo install --features mcp.
Running Queries — what the reason tool evaluates.

Backlinks

Linked Pages

Running Queries

Once your vault contains some SPL, zetl reason is how you ask questions of it. This page walks the everyday command surface: status, conflicts, export, and provenance.

Requires --features reason at install. See Installation.

`reason status` — the default view

zetl reason status prints every conclusion the combined theory produces, tagged with +D, -D, +d, or -d (see What is Defeasible Reasoning for what those mean).

cd ~/notes
zetl reason status

In a TTY you get a table. Piped or redirected, you get JSON — same data, machine-readable.

Filters

Status output gets long fast. A few flags keep it manageable:

Flag	Shows
`--positive`	Only `+D` and `+d` conclusions
`--negative`	Only `-D` and `-d` conclusions
`--definite`	Only `+D` and `-D` (the strict layer)
`--defeasible`	Only `+d` and `-d` (the soft layer)
`--literal "release*"`	Wildcard filter on the literal name (`*` and `?` supported)

Combine them. “What are all the things my Acme project is currently defeasibly committed to?” becomes:

zetl reason status --positive --defeasible --literal "acme*"

Installation

zetl ships prebuilt binaries for Linux, macOS, and Windows. The installer script handles platform detection, download, and wiring up the man page and shell completions. If you prefer to build from source, that path is documented below too.

Prebuilt binaries (recommended)

macOS and Linux:

curl -fsSL https://files.anuna.io/zetl/latest/install.sh | bash

The script detects your OS and architecture, downloads the right tarball, installs the binary to ~/.local/bin, and generates the man page and shell completions.

Windows:

Download zetl-windows-x86_64.zip from files.anuna.io/zetl/latest, extract zetl.exe, and place it somewhere on your PATH.

Pinning to a specific version

VERSION=0.6.1 curl -fsSL https://files.anuna.io/zetl/latest/install.sh | bash

Custom install location

INSTALL_DIR=/usr/local/bin curl -fsSL https://files.anuna.io/zetl/latest/install.sh | bash

Capability URLs

Capability mode is zetl’s answer to: “I want to share my wiki with a dozen friends, read-only, without running a server, but I don’t want the whole internet reading it.” The output is a plain static site — hostable on any CDN, any S3 bucket, any sftp’d directory — where access is gated by a secret in the URL fragment. No accounts, no server-side auth, nothing to rotate but the URLs themselves.

If you want multi-user editing, you want Running a Team Server. Capability mode is for publishing.

The idea in one paragraph

Each page is encrypted at build time with a cohort-specific key. Invite URLs look like https://wiki.example.com/welcome.html#k=<base64-secret>. The #fragment — by design of the HTTP spec — is never sent to the server. The reader’s browser, executing a small JavaScript shim, pulls the key out of the fragment, decrypts the page locally, and verifies a vault-level Ed25519 signature so nobody can serve them a forged page. Revocation is per-cohort: you rotate the cohort’s salt and re-deploy, old URLs stop decrypting.

Formal spec: see docs/capability-mode.md in the zetl repo.

Setting up a capability site

1. Generate the keys

zetl cap genkey

This prints two secrets to stdout, exactly once:

ZETL_CAP_SECRET — the 48-byte content-encryption secret.
ZETL_CAP_SIGNING_KEY — the Ed25519 vault-signing private key.

Capture them somewhere safe (a secret store, a password manager, a sealed envelope). You’ll need ZETL_CAP_SECRET on every build and ZETL_CAP_SIGNING_KEY whenever you rotate the signing key.

Running a Team Server

zetl’s --collab flag turns zetl serve into a multi-user editing server: passkey login, real-time CRDT co-editing, per-user git commits, and scoped invitations. Everything is in-tree — there’s no feature flag to enable at install time. If you can run zetl serve, you can run a team server.

The shape of a collab vault

A collab vault is a normal Markdown vault plus a .zetl/collab/ directory:

.zetl/collab/server.key — the server’s Ed25519 signing key (for session cookies and invitations).
.zetl/collab/users.db — SQLite store for passkeys, sessions, and invitation nonces.
.zetl/collab/wal/ — write-ahead log for the CRDT engine. Survives crashes.

These files are created on first run. You never edit them by hand.

First run: bootstrap the owner

The very first time you start a collab server, you need to bootstrap an owner account. --init-owner creates one, prints a 12-word recovery phrase, and exits into the normal serve loop:

zetl -d ~/notes serve --collab --init-owner --owner-name Alice

The terminal will print something like:

Owner created: Alice
Recovery phrase (write this down — you will not see it again):

  palm  tornado  ladder  oyster  casual  umbrella
  desert  finger  enlist  brave  coconut  strong

Server listening on http://localhost:3000

Save that phrase. It’s your only way back into the account if you lose your passkey, and zetl will not show it to you a second time. Paper, password manager, encrypted notes file — pick one and commit.

Lifecycle Hooks

Git-style scripts that run at defined points during a zetl operation. Drop an executable into .zetl/hooks/ named after a lifecycle point, and zetl invokes it with structured JSON on stdin and a handful of ZETL_* environment variables.

These are separate from the AST-level Render Pipeline Hooks — lifecycle hooks fire around the build, not inside it. Use them to publish an RSS feed after zetl build, notify a chat room on on-save, or run a schema validator on post-check.

Lifecycle points

Hook	Fires	Can abort?
`pre-build`	Before `zetl build` renders pages	Yes
`post-build`	After `zetl build` completes	No (warning on non-zero)
`post-index`	After `zetl index` completes	No
`post-check`	After `zetl check` collects diagnostics	No
`pre-serve`	Before `zetl serve` binds	Yes
`on-save`	After a page is saved via `zetl serve`	No
`on-agent`	When an agent API request arrives	No
`on-access-request`	When a user requests page access (collab mode)	No

“Can abort” means a non-zero exit cancels the parent operation; every other hook just logs a warning and continues.

What a hook receives

stdin — a JSON object with vault metadata, the page list, the link graph, and hook-specific fields (e.g. saved for on-save). If history is enabled, a history object is included.
environment — ZETL_HOOK (the lifecycle name), ZETL_VAULT_ROOT, ZETL_THEME, ZETL_VERSION, plus hook-specific vars: ZETL_OUT_DIR on build hooks, ZETL_PORT on serve hooks.
working directory — the vault root, regardless of where zetl was invoked from.
timeout — 30 seconds wall-clock. A hook that hangs is killed.

Writing a hook

Create an executable file named exactly after the lifecycle point (no extension):

# .zetl/hooks/post-build
#!/bin/bash
# Generate an RSS feed from pages with a `date:` frontmatter field.
set -euo pipefail

jq -r '
  .pages
  | map(select(.frontmatter.date))
  | sort_by(.frontmatter.date) | reverse | .[0:20]
  | map("<item><title>\(.title)</title><pubDate>\(.frontmatter.date)</pubDate></item>")
  | "<rss><channel>\(join(""))</channel></rss>"
' < /dev/stdin > "$ZETL_OUT_DIR/feed.xml"

Then mark it executable:

chmod +x .zetl/hooks/post-build

Web Server

zetl serve starts a local web server that renders your vault as a browsable site. You get rendered Markdown, working wikilinks, a live backlink panel, a persistent graph mini-map, and an in-browser editor. It’s the fastest way to actually read — and edit — a vault of more than a handful of notes.

Why run a server

A static export (Static Site Export) shows your vault as it was when you last built it. A terminal viewer (Terminal Viewer) shows one note at a time. zetl serve is what you want between those: a live view of the vault right now, with:

Rendered pages — Markdown, wikilinks, embeds, and code blocks, rendered through Minijinja templates with YAML frontmatter in scope.
Backlinks panel — every page that points here, updated on every save.
Transclusion panel — forward-link excerpts as cards in the right rail, connected to anchors in the main text by SVG bridges (the same Xanadu idea as the terminal viewer).
Live search — full-text search across the vault from a modal.
CodeMirror editor — click Edit, change the note, hit Save. The index rebuilds on save; no reload dance. A delete button is a click away.
Persistent graph mini-map — a Sigma.js WebGL graph of your vault, docked bottom-right, that survives page navigation (no flash, no re-layout).
History strip — when zetl was built with --features history, every page shows when it last changed and links to its timeline. See Page History.

Running it

zetl serve                            # http://localhost:3000
zetl -d ~/notes serve
zetl serve --port 8080
zetl serve --theme paper

Open http://localhost:3000/ to land on the vault index. Wikilinks in rendered pages are clickable. Ctrl-P (or whatever the active theme binds) opens the search modal.

Flags that matter

Flag	Default	Purpose
`-p, --port <PORT>`	`3000`	TCP port.
`--theme <THEME>`	`default`	Theme from `.zetl/themes/<name>/`. See Customising the Look.
`--public <DIR>`	—	Files in this directory override generated pages (good for `robots.txt`, custom error pages).
`--collab`	off	Switches to multi-user mode with passkeys and CRDT sync. See Running a Team Server.
`--safe-mode`	off	Skip every hook except ones declared in the theme.
`--at <TIME-EXPR>`	—	Serve a past snapshot. See Time Travel.
`--exclude <PATTERN>`	—	Gitignore-syntax exclusion, repeatable.

Single-user vs collab

Out of the box, zetl serve is single-user and trusts whoever reaches the port. There’s no login, no accounts; editing works immediately. This is the right mode when the server is on your laptop or behind a VPN.

With --collab, zetl turns into a multi-user server: WebAuthn passkey login, real-time CRDT editing over WebSockets, access control, invitations. That whole stack — bootstrapping an owner, inviting collaborators, deterministic server keys — lives in Running a Team Server.

What is Defeasible Reasoning

A short primer on the kind of logic zetl uses when you ask it to reason over your notes. No symbols, no formal notation — just an explanation of why this flavour of logic suits knowledge work.

Requires --features reason at install. See Installation.

Classical logic: everything is final

In classical logic, facts combine and the conclusion is permanent. If you write down that every bird flies, and that Tweety is a bird, then Tweety flies. Forever. Adding new information can only produce new conclusions — it can never retract one you already made.

That rule works beautifully inside a maths textbook. It breaks almost immediately when you try to write down the actual state of a research project, a release plan, or a set of beliefs you formed over six months of reading. Real knowledge is provisional. You revise it. You hedge. You say “normally X, but not when Y”.

Defeasible logic: conclusions have strength

Defeasible reasoning lets you write rules that are normally true but can be defeated by stronger evidence. In a project-tracking vault you might write:

Normally, a release candidate is ready if core features are done, docs are written, and tests pass.
Except when there is an outstanding critical bug.

Both rules live in the theory at the same time. When zetl reasons over them, the defeater wins if its conditions hold — the release is blocked. If the bug is later fixed, the block lifts and the conclusion flips. You never rewrote the rules; you just added and removed facts.

This is exactly how thinking about ongoing work feels. “We’re on track — unless the client pushes back on the design.” “The proposal is done — except we still need a legal review.” You already reason this way. zetl just gives you a notation for it.

Similar Pages

zetl similar "Query" finds pages whose titles are near-matches for the query string. It uses SimHash over page names, which makes it excellent at three things: recovering from typos, spotting duplicate-ish pages you meant to merge, and suggesting links as you type.

zetl similar "Zetelkasten Method"

Zettelkasten Method        (distance 3)
Zettelkasten Workflow      (distance 7)
Luhmann's Method           (distance 11)

The number is Hamming distance on the hash — smaller is more similar. Zero would be identical.

What SimHash does, briefly

SimHash is a locality-sensitive hash: feed it a string, get back a fixed-length binary fingerprint such that similar strings produce similar fingerprints. Unlike a cryptographic hash (where flipping one letter scrambles the whole output), SimHash changes only a few bits when the input changes slightly. Comparing two hashes by Hamming distance — the count of differing bits — gives you a cheap similarity score without storing the originals.

zetl computes one hash per page name at index time. zetl similar then scans them and returns the closest N. No full-text comparison, no embedding model, no network — just arithmetic over bits. It finishes in under a millisecond for vaults of tens of thousands of pages.

The tradeoff: it only sees names. A page titled Dogs and a page titled Canine Companions are not similar to SimHash, even though they are the same topic. For content similarity, use zetl search --semantic (see Searching).

The three flags

Flag	Default	Use
`--threshold N`	`12`	Max Hamming distance to report. Lower = stricter
`--limit N`	`10`	Max results
`--json`	off	Force JSON output

The default threshold of 12 is tuned to catch typos and near-duplicates without flooding the output. Lower it to 6 if you only want obvious matches; raise it to 20 to see the long tail.

When to use it

Wikilinks

A wikilink is how you point from one note to another by name. zetl parses five shapes of wikilink from your Markdown. This page is the syntax reference; for workflow advice see Linking Pages.

The five shapes

Shape	Example	Purpose
Plain	`[[Zettelkasten Method]]`	Link to a page; display text is the target name
Aliased	`[[Zettelkasten Method\|the slip-box method]]`	Link with custom display text
Heading	`[[Zettelkasten Method#Origins]]`	Link to a specific heading on a page
Block	`[[Zettelkasten Method^b3a9f1]]`	Link to a specific content-addressable block
Embed	`![[Zettelkasten Method]]`	Transclude the target’s content inline (see Embeds and Transclusion)

All five can be combined with a heading or block anchor on the target side: ![[Zettelkasten Method#Origins]] embeds a single section.

How resolution works

When you write [[Some Page]], zetl does not look up a URL or an ID. It looks for a file named Some Page.md in your vault. Specifically:

By filename, not by the # H1 inside the file. The name in brackets must match the file stem.
Case-insensitive. [[some page]], [[SOME PAGE]], and [[Some Page]] all resolve to Some Page.md.
Across subfolders. zetl searches the whole vault tree; you don’t write [[projects/zetl]], just [[zetl]].
Slugified for the web output — Some Page.md becomes /page/some-page/ in zetl serve and zetl build. You never need to think about slugs when writing; that’s what the resolver is for.

If two files share a name across folders, the first match wins and the other is reported as ambiguous by zetl check. Rename one.

Dead links are fine (until they’re not)

A wikilink to a page that does not yet exist is a dead link. zetl does not crash, does not refuse to render, and does not auto-create the file. It records the edge and surfaces it in:

zetl check --dead-links

Many people use this as a to-do list: write what you wish existed, then fill in the targets later. See Finding Orphans and Dead Links.