MCP Server

The MCP (Model Context Protocol) server exposes ztlctl's discovery-first tool surface to AI clients. The server registers 73 tools auto-generated from the ActionRegistry — every CLI command has a corresponding MCP tool with the same parameters and return schema.

Setup¶

# Install with MCP support
pip install ztlctl[mcp]

# Start the server
ztlctl serve --transport stdio

Claude Desktop Integration¶

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "ztlctl": {
      "command": "ztlctl",
      "args": ["serve"]
    }
  }
}

Discovery Pattern¶

The intended call sequence is:

discover_tools to narrow the surface by category
describe_tool to inspect a specific contract
ztlctl://agent-reference when the client needs a single onboarding payload

Tool Categories¶

Category	Tools
Discovery	`discover_tools`, `describe_tool`, `list_tags`, `list_source_providers`
Creation	`create_note`, `create_reference`, `create_task`, `create_log`, `garden_seed`, `ingest_source`
Lifecycle	`update_content`, `close_content`, `reweave`
Query	`search`, `get_document`, `get_related`, `agent_context`, `list_items`, `work_queue`, `topic_packet`, `draft_from_topic`
Analysis	`decision_support`, `vault_review`, `check_contradictions`, `confirm_contradiction`
Graph	`graph_themes`, `graph_rank`, `graph_path`, `graph_gaps`, `graph_bridges`
Session	`session_close`, `session_status`, `recall_temporal`, `recall_topic`, `recall_topology`
Check	`check_alignment`
Ingest	`ingest_media`

Notable additions for agent workflows:

ingest_source normalizes text, files, and provider-backed URLs into notes or references
ingest_source accepts a nested source_bundle contract for agent-fetched web and multimodal captures, while still supporting the older flat evidence fields
ingested references persist source bundles under sources/<reference-id>/ so later packets, drafts, and dossier exports can reuse the same evidence
list_source_providers lets clients discover installed URL-ingestion providers
topic_packet assembles topic-scoped learning, review, and decision bundles
draft_from_topic turns a topic packet into a note, task, or decision draft without writing to the vault
create_note accepts authored body, key_points, aliases, and links
create_reference accepts subtype for article, tool, or spec
vault_review returns a review-ready aggregate snapshot
session_status lets clients reason about active-session state without inferring from errors

Generated Client Assets¶

For project-local Claude and Codex setup, export generated workflow assets from the packaged templates:

ztlctl workflow export --client both

This writes a .claude/ project bundle, a root AGENTS.md, and supporting files derived from the same portable workflow source. The exported guidance treats MCP as canonical when available and the CLI as the fallback contract.

Available Resources¶

20 resources are registered by default. All URIs use the ztlctl:// scheme.

Resource	Description
`ztlctl://self/identity`	Agent identity document
`ztlctl://self/methodology`	Agent methodology document
`ztlctl://overview`	Vault statistics and structure
`ztlctl://work-queue`	Prioritized task list
`ztlctl://review/dashboard`	External review workbench snapshot
`ztlctl://garden/backlog`	Enrichment backlog signals from stale seeds and orphan notes
`ztlctl://decision-queue`	Recent decisions plus active work queue
`ztlctl://capture/spec`	Source-bundle contract for agent capture and ingest handoff
`ztlctl://topics`	Available topic directories
`ztlctl://context`	Full assembled context (identity + methodology + overview)
`ztlctl://agent-reference`	Onboarding payload with tool guidance and workflow examples
`ztlctl://recipes`	Index of available agent orchestration recipes
`ztlctl://recipes/research-capture`	Research-capture workflow: search, create notes, link evidence
`ztlctl://recipes/review-triage`	Review-triage workflow: work queue, inspect, update, archive
`ztlctl://recipes/knowledge-synthesis`	Knowledge-synthesis workflow: search, find gaps, draft, reweave
`ztlctl://docs/index`	Navigation map of all ztlctl documentation pages
`ztlctl://docs/search`	Documentation search guidance — use `docs_search` tool for queries
`ztlctl://polaris`	The vault's polaris priorities document — see Polaris priorities
`ztlctl://sessions/recent`	Recent session summaries for temporal recall — see Session recall
`ztlctl://review/contradictions`	Contradiction candidate pairs for agent review — see Contradiction detection

Available Prompts¶

9 prompts are registered by default (source: src/ztlctl/mcp/prompts.py).

Prompt	Description
`research_session`	Start a structured research session
`knowledge_capture`	Guided knowledge capture workflow
`vault_orientation`	Orient to the current vault state
`decision_record`	Record an architectural decision
`topic_learn`	Gather and learn from a topic packet
`topic_review`	Review a topic for stale and weakly connected knowledge
`topic_decision`	Prepare a decision-ready topic packet and draft
`capture_web_source`	Turn a fetched web page into a source bundle for ingest
`capture_multimodal_source`	Turn extracted multimodal evidence into a source bundle for ingest

Example: Creating a Note via MCP¶

A complete create_note tool call and response:

// Tool call
{
  "tool": "create_note",
  "arguments": {
    "title": "Zettelkasten Linking Principles",
    "body": "Each note should represent a single atomic idea...",
    "tags": ["zettelkasten", "methodology"],
    "maturity": "seed"
  }
}

// Response
{
  "ok": true,
  "content_id": "ztl_A3F8B2C1",
  "title": "Zettelkasten Linking Principles",
  "path": "notes/zettelkasten/ztl_A3F8B2C1.md",
  "maturity": "seed",
  "tags": ["zettelkasten", "methodology"],
  "links_added": 0
}

After creation, run reweave with the returned content_id to discover and add connections to related notes automatically.

Agent Integration¶

For machine-readable schemas, state machines, and structured interaction flows, see the Agent System Manual. That page is optimized for LLM consumers and covers error recovery patterns, constraint rules, and orchestration contracts.