Skip to main content

​
Anthropic MCP Integration

z3rno-mcp is a Model Context Protocol server that exposes Z3rno’s seven verbs — and the conversation + temporal primitives that ride on top of them — as twelve tools any MCP-compatible host can call. Drop it into Claude Desktop, Cursor, or Claude Code and the agent inherits persistent memory, an audit trail, and a knowledge graph without any code on your side.
Requires a running Z3rno server. Spin one up locally with docker compose -f docker-compose.dev.yml up from z3rno-server, or point at a self-hosted instance.

​
Install

# Run directly (recommended — no install step, always latest)
uvx z3rno-mcp

# Or install into your environment
pip install 'z3rno-mcp>=0.6.1'
z3rno-mcp ships on PyPI. The package pins z3rno (the Python SDK) >=0.7.0, so all twelve tools — including the Forge verbs (ingest, distill, refine), conversation primitives, and temporal recall — are available out of the box.

​
Configure your MCP host

// ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
// %APPDATA%\Claude\claude_desktop_config.json (Windows)
{
  "mcpServers": {
    "z3rno": {
      "command": "uvx",
      "args": ["z3rno-mcp"],
      "env": {
        "Z3RNO_BASE_URL": "http://localhost:8000",
        "Z3RNO_API_KEY": "z3rno_sk_test_localdev",
        "Z3RNO_AGENT_ID": "claude-desktop"
      }
    }
  }
}
Restart your MCP host. The twelve z3rno.* tools should appear in the tool picker.

​
Environment variables

VariableRequiredDefaultNotes
Z3RNO_BASE_URLnohttps://api.z3rno.devURL of the z3rno-server you want to talk to. For local dev use http://localhost:8000.
Z3RNO_API_KEYyes—API key. The default dev key on a fresh local server is z3rno_sk_test_localdev.
Z3RNO_AGENT_IDno—Default agent id used when a tool call omits one. Without it every tool call must pass agent_id explicitly.
Z3RNO_WEB_URLnohttps://app.z3rno.devBase URL the z3rno.visualize_url tool returns links against.

​
Tools

z3rno-mcp exposes twelve tools, grouped by what they touch.

​
Memory primitives

​
z3rno.store
tool
Store a memory in Z3rno. Persists facts, preferences, decisions, or anything the agent should remember across conversations. Returns the stored memory and its id.
​
z3rno.recall
tool
Semantic search over memories. Defaults to the AUTO strategy router which picks VECTOR, GRAPH, LEXICAL, TEMPORAL, TRACE, TRIPLET, CYPHER, or CODE per query. Returns ranked results with similarity scores.
​
z3rno.forget
tool
Soft-delete (default) or hard-delete a memory. Use hard_delete=true to satisfy GDPR right-to-erasure — the row is removed and a Merkle-rooted, ed25519-signed certificate is emitted to forget_certificates.
​
z3rno.audit
tool
Paginated query over the immutable audit log: every store / recall / forget / distill operation, hash-chained per tenant. Useful for compliance and debugging.

​
Forge (knowledge graph)

​
z3rno.ingest
tool
Push raw text or a URL into the Forge. Returns a job_id; the server chunks, embeds, and (when INGEST_AUTO_DISTILL=true, the default) chains directly into z3rno.distill. File uploads aren’t supported via MCP — use the HTTP /v1/ingest/file endpoint for those.
​
z3rno.distill
tool
Build or extend the knowledge graph from stored memories. Runs the Forge pipeline: chunk → LLM entity + relationship extraction → write Memo nodes + edges. Returns a job_id; poll with poll_job_id=<id>. Idempotent.
​
z3rno.refine
tool
Improve the graph in place: dedupe Memos sharing an ontology URI or normalized name (SCD-2 supersede), EMA-blend edge weights from accumulated feedback, prune sub-threshold edges. Optional LLM stages (infer / summarize) are server-side flags. Admin-scoped.
​
z3rno.visualize_url
tool
Return a URL to the Z3rno graph viewer for a dataset or agent. Use when the user asks “show me the graph”. The viewer (z3rno-web /graph) renders the Memo subgraph in Cytoscape.

​
Conversation memory (Phase G)

​
z3rno.start_conversation
tool
Open a new conversation. Returns the conversation_id so subsequent stores can be tagged. Call this at the start of a chat — the resulting id enables turn-aware recall and automatic summarization triggers.
​
z3rno.end_conversation
tool
Mark a conversation finished. The metadata row is soft-deleted and no further turns can be added; existing turn Memos stay queryable via standard recall.
​
z3rno.summarize_conversation
tool
Fetch turn history in order so the agent can produce a summary. The agent runs its own summarization; once done, it persists the result via z3rno.store with memory_type='semantic' and metadata={'kind': 'summary', 'covers_turns': [start, end]}.
​
z3rno.time_travel
tool
Recall memories as they existed at a past timestamp. Uses Z3rno’s SCD-2 temporal index. Supply an ISO-8601 timestamp like 2026-01-15T12:00:00Z. Useful for “what did I tell you last week?” and compliance investigations.

​
Worked example

This is what a turn looks like from Claude Desktop once the MCP server is wired in. The user types in chat; Claude calls the tools.
User
Remember that I'm allergic to penicillin.
Tool call
{
  "tool": "z3rno.store",
  "args": {
    "content": "User is allergic to penicillin",
    "memory_type": "semantic",
    "importance": 0.95
  }
}
User (a week later)
Can you prescribe me amoxicillin?
Tool call
{
  "tool": "z3rno.recall",
  "args": {
    "query": "user allergies medication contraindications",
    "top_k": 5
  }
}
Claude reads the recall results, sees the penicillin allergy (amoxicillin is in the same family), and warns the user — without you having written any prompt-engineering glue.
User
Show me the audit trail for today.
Tool call
{
  "tool": "z3rno.audit",
  "args": {
    "limit": 50
  }
}

​
Adding a conversation

For multi-turn sessions where you want turn-aware recall and audit-friendly history: 
// Start
{ "tool": "z3rno.start_conversation", "args": {} }
// → { "conversation_id": "conv_abc123" }

// Store turns (Claude does this automatically per message)
{ "tool": "z3rno.store",
  "args": { "content": "User said: I prefer dark mode",
            "memory_type": "episodic",
            "metadata": { "conversation_id": "conv_abc123", "role": "user" } } }

// Scope recall to this conversation
{ "tool": "z3rno.recall",
  "args": { "query": "ui preferences", "conversation_id": "conv_abc123" } }

// End (soft-deletes the row; turns stay queryable)
{ "tool": "z3rno.end_conversation",
  "args": { "conversation_id": "conv_abc123" } }

​
Troubleshooting

Check the host’s MCP log:
  • Claude Desktop: ~/Library/Logs/Claude/mcp.log (macOS) or %APPDATA%\Claude\logs\mcp.log (Windows)
  • Cursor: open the command palette → “MCP: Show Server Logs”
Most common cause: uvx not on PATH. Run which uvx in a terminal — if empty, install uv from astral.sh/uv.
Either set Z3RNO_AGENT_ID in the env block of your config, or pass agent_id on every tool call. The default mode is “no implicit agent” so multi-agent setups don’t accidentally cross-write.
Verify Z3RNO_API_KEY matches the server. For a fresh local server the dev key is z3rno_sk_test_localdev. If you’ve rotated it, fetch the current value from your .env. For production, generate a new key via POST /v1/api-keys.
The graph viewer hasn’t been deployed yet at the URL the tool returns. Either run z3rno-web locally (npm run dev from the z3rno-web repo) and set Z3RNO_WEB_URL=http://localhost:3000, or wait for the hosted viewer to land at app.z3rno.dev/graph.

​
Reference