> ## Documentation Index
> Fetch the complete documentation index at: https://astron-bb4261fd.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# z3rno-mcp

> MCP server that exposes Z3rno's seven verbs (plus conversation + temporal primitives) as twelve tools for Claude Desktop, Cursor, Claude Code, and any MCP-compatible host.

## Overview

`z3rno-mcp` is a Model Context Protocol server that wraps the Python SDK and surfaces it over stdio. Drop it into Claude Desktop, Cursor, Claude Code, or any MCP-compatible runtime and the agent inherits persistent memory, an immutable audit log, knowledge-graph extraction, and turn-aware conversation memory — without any code on your side.

<Note>
  For a step-by-step install + walkthrough optimized for Claude Desktop, see [Integrations → Anthropic MCP](/integrations/anthropic-mcp). This page is the reference: every tool, every parameter, every env var.
</Note>

**Current version:** `z3rno-mcp 0.6.1` (pins `z3rno` SDK `>=0.7.0`).

## Tools

Twelve tools, grouped by what they touch.

### Memory primitives

#### `z3rno.store`

Persist a memory. Returns the stored memory and its id.

```json theme={null}
{
  "content": "User prefers dark mode and Python",
  "agent_id": "claude-desktop",
  "memory_type": "episodic",
  "user_id": "user_abc",
  "metadata": { "source": "preferences-survey" },
  "importance": 0.8,
  "ttl_seconds": 86400
}
```

| Field         | Type   | Default               | Notes                                                                      |
| ------------- | ------ | --------------------- | -------------------------------------------------------------------------- |
| `content`     | string | required              | The fact / preference / decision to persist.                               |
| `agent_id`    | string | from `Z3RNO_AGENT_ID` | Falls back to the env var when unset; errors if neither is set.            |
| `memory_type` | string | `"episodic"`          | One of `episodic`, `semantic`, `procedural`, `working`.                    |
| `user_id`     | string | —                     | Optional end-user identifier for multi-user agents.                        |
| `metadata`    | object | —                     | Arbitrary JSON; useful for `{ "conversation_id": "...", "role": "user" }`. |
| `importance`  | float  | —                     | 0.0–1.0; influences the importance-decay lifecycle.                        |
| `ttl_seconds` | int    | —                     | Optional time-to-live; omitted = no expiry.                                |

#### `z3rno.recall`

Semantic search. Defaults to the `AUTO` strategy router which picks `VECTOR`, `GRAPH`, `LEXICAL`, `TEMPORAL`, `TRACE`, `TRIPLET`, `CYPHER`, or `CODE` per query.

```json theme={null}
{
  "query": "What are the user's UI preferences?",
  "agent_id": "claude-desktop",
  "memory_type": "semantic",
  "top_k": 5,
  "similarity_threshold": 0.7,
  "filters": { "metadata": { "source": "preferences-survey" } }
}
```

| Field                  | Type   | Default  | Notes                                                            |
| ---------------------- | ------ | -------- | ---------------------------------------------------------------- |
| `query`                | string | required | Free-text query.                                                 |
| `agent_id`             | string | from env | Falls back to `Z3RNO_AGENT_ID`.                                  |
| `memory_type`          | string | —        | Optional filter.                                                 |
| `top_k`                | int    | `10`     | Result count.                                                    |
| `similarity_threshold` | float  | `0.0`    | Drops results below this cosine score.                           |
| `filters`              | object | —        | Server-side WHERE-clause kwargs (e.g. `metadata`, `dataset_id`). |

#### `z3rno.forget`

Soft-delete (default) or hard-delete one or more memories. Hard delete emits a Merkle-rooted, ed25519-signed certificate to `forget_certificates` for GDPR right-to-erasure compliance.

```json theme={null}
{
  "memory_id": "550e8400-e29b-41d4-a716-446655440000",
  "hard_delete": true,
  "cascade": false,
  "reason": "User requested data erasure"
}
```

| Field         | Type   | Default  | Notes                                                              |
| ------------- | ------ | -------- | ------------------------------------------------------------------ |
| `memory_id`   | string | —        | Single-id form.                                                    |
| `memory_ids`  | array  | —        | Batch form. Exactly one of `memory_id` / `memory_ids` is required. |
| `agent_id`    | string | from env | Scopes the delete.                                                 |
| `hard_delete` | bool   | `false`  | `true` = irrecoverable; emits a forget certificate.                |
| `cascade`     | bool   | `false`  | Also forget Memos extracted from this memory by the Forge.         |
| `reason`      | string | —        | Logged on the audit row.                                           |

#### `z3rno.audit`

Paginated read over the hash-chained audit log.

```json theme={null}
{
  "agent_id": "claude-desktop",
  "operation": "store",
  "page": 1,
  "page_size": 50
}
```

| Field       | Type   | Default                      |
| ----------- | ------ | ---------------------------- |
| `agent_id`  | string | from env                     |
| `operation` | string | — (returns all ops if unset) |
| `memory_id` | string | —                            |
| `page`      | int    | `1`                          |
| `page_size` | int    | `50`                         |

### Forge (knowledge graph)

#### `z3rno.ingest`

Push raw text or a URL into the Forge. Returns a `job_id`; when `INGEST_AUTO_DISTILL=true` (the default), the server chains directly into `z3rno.distill`.

```json theme={null}
{ "kind": "text", "text": "..." }
{ "kind": "url",  "url":  "https://example.com/article" }
```

| Field        | Type                | Notes                                                                                                |
| ------------ | ------------------- | ---------------------------------------------------------------------------------------------------- |
| `kind`       | `"text"` \| `"url"` | Required. File uploads aren't supported via MCP — use the HTTP `/v1/ingest/file` endpoint for those. |
| `text`       | string              | Required when `kind="text"`.                                                                         |
| `url`        | string              | Required when `kind="url"`.                                                                          |
| `agent_id`   | string              | from env.                                                                                            |
| `dataset_id` | string              | Optional dataset to scope the ingest into.                                                           |

#### `z3rno.distill`

Build or extend the knowledge graph from stored memories. Runs the Forge pipeline (chunk → LLM entity + relationship extraction → write Memo nodes + edges) and returns a `job_id`. Poll status with `poll_job_id`. Idempotent.

```json theme={null}
// kick off
{ "memory_ids": ["m1", "m2"], "agent_id": "claude-desktop" }

// poll
{ "poll_job_id": "job_xyz" }
```

#### `z3rno.refine`

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.

```json theme={null}
{ "dataset_id": "ds_abc" }
{ "poll_job_id": "job_xyz" }
```

#### `z3rno.visualize_url`

Return a URL to the Z3rno graph viewer for a dataset or agent. Use when the user asks "show me the graph".

```json theme={null}
{ "dataset_id": "ds_abc", "agent_id": "claude-desktop" }
```

Returns a string URL of the form `${Z3RNO_WEB_URL}/graph?dataset_id=...`.

### Conversation memory (Phase G)

#### `z3rno.start_conversation`

Open a new conversation. Returns the `conversation_id` so subsequent stores can be tagged. Call at the start of a chat to enable turn-aware recall and automatic summarization triggers.

```json theme={null}
{
  "agent_id": "claude-desktop",
  "user_id": "user_abc",
  "title": "Allergy intake",
  "summary_cadence": 10
}
```

| Field             | Type   | Default  | Notes                                       |
| ----------------- | ------ | -------- | ------------------------------------------- |
| `agent_id`        | string | from env |                                             |
| `user_id`         | string | —        |                                             |
| `title`           | string | —        | Display label for dashboards.               |
| `summary_cadence` | int    | `10`     | Trigger `needs_summary` flag every N turns. |

#### `z3rno.end_conversation`

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.

```json theme={null}
{ "conversation_id": "conv_abc123" }
```

#### `z3rno.summarize_conversation`

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]}`.

```json theme={null}
{
  "conversation_id": "conv_abc123",
  "after_turn": 0,
  "limit": 50
}
```

#### `z3rno.time_travel`

Recall memories as they existed at a past timestamp. Uses Z3rno's SCD-2 temporal index. Supply an ISO-8601 timestamp.

```json theme={null}
{
  "as_of": "2026-01-15T12:00:00Z",
  "query": "user allergies",
  "agent_id": "claude-desktop",
  "conversation_id": "conv_abc123",
  "top_k": 10
}
```

## Environment variables

| Variable         | Required | Default                 | Notes                                                                                                          |
| ---------------- | -------- | ----------------------- | -------------------------------------------------------------------------------------------------------------- |
| `Z3RNO_API_KEY`  | **yes**  | —                       | API key. The dev default on a fresh local server is `z3rno_sk_test_localdev`.                                  |
| `Z3RNO_BASE_URL` | no       | `https://api.z3rno.dev` | Server URL. Override to `http://localhost:8000` for local dev.                                                 |
| `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.                                                 |

## Install

```bash theme={null}
# Run directly (recommended — no install step, always latest)
uvx z3rno-mcp

# Or install into your environment
pip install 'z3rno-mcp>=0.6.1'

# Or from source
git clone https://github.com/the-ai-project-co/z3rno-mcp
cd z3rno-mcp
uv sync
uv run z3rno-mcp
```

## Host configuration

<CodeGroup>
  ```json Claude Desktop theme={null}
  // ~/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"
        }
      }
    }
  }
  ```

  ```json Cursor theme={null}
  // .cursor/mcp.json (per-workspace) or ~/.cursor/mcp.json (global)
  {
    "mcpServers": {
      "z3rno": {
        "command": "uvx",
        "args": ["z3rno-mcp"],
        "env": {
          "Z3RNO_BASE_URL": "http://localhost:8000",
          "Z3RNO_API_KEY": "z3rno_sk_test_localdev",
          "Z3RNO_AGENT_ID": "cursor"
        }
      }
    }
  }
  ```

  ```json Claude Code theme={null}
  // ~/.claude/settings.json
  {
    "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-code"
        }
      }
    }
  }
  ```
</CodeGroup>

## Self-hosted

Point the MCP server at your own Z3rno instance — works identically whether the server runs from `docker compose` locally or from the Helm chart on a cluster:

```bash theme={null}
export Z3RNO_BASE_URL=http://localhost:8000
export Z3RNO_API_KEY=z3rno_sk_test_localdev
export Z3RNO_AGENT_ID=my-agent
uvx z3rno-mcp
```

## Troubleshooting

* **Tools don't appear** — `uvx` not on PATH. Run `which uvx`; if empty, install `uv` from [astral.sh/uv](https://docs.astral.sh/uv/getting-started/installation/).
* **`agent_id is required`** — Set `Z3RNO_AGENT_ID` in the env block, or pass `agent_id` on every tool call. No implicit fallback by design.
* **Connection refused** — Verify `Z3RNO_BASE_URL` is reachable and the server is running (`curl $Z3RNO_BASE_URL/v1/health`).
* **401 Unauthorized** — Verify `Z3RNO_API_KEY` matches the server. Default dev key is `z3rno_sk_test_localdev`; rotate for production via `POST /v1/api-keys`.
* **`z3rno.visualize_url` returns a 404** — The graph viewer at the returned URL isn't deployed. Run `z3rno-web` locally and set `Z3RNO_WEB_URL=http://localhost:3000`, or wait for the hosted viewer to land at `app.z3rno.dev/graph`.