Anthropic MCP

Plug Z3rno into Claude Desktop, Cursor, Claude Code, or any MCP-compatible runtime via the z3rno-mcp server.

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

Claude Desktop

// ~/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

Variable	Required	Default	Notes
Z3RNO_BASE_URL	no	https://api.z3rno.dev	URL of the z3rno-server you want to talk to. For local dev use http://localhost:8000.
Z3RNO_API_KEY	yes	—	API key. The default dev key on a fresh local server is z3rno_sk_test_localdev.
Z3RNO_AGENT_ID	no	—	Default agent id used when a tool call omits one. Without it every tool call must pass agent_id explicitly.
Z3RNO_WEB_URL	no	https://app.z3rno.dev	Base 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

Tools don't show up after restart

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.

`agent_id is required` errors

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.

Authentication errors (401)

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.

`z3rno.visualize_url` returns a 404

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

• Package: z3rno-mcp on PyPI — current version 0.6.1
• Source: github.com/the-ai-project-co/z3rno-mcp
• Underlying SDK: z3rno on PyPI — pinned >=0.7.0
• Server: see Components → z3rno-server for the full v1 surface the tools call into
• Verbs: see Concepts → The Z3rno Verbs for the canonical seven-verb table