MCP tools

eidetic-mcp is a Python wrapper exposing the daemon's UDS API as MCP tools. Process-isolated from the daemon (separate install, separate crash surface). 13 tools live in eidetic-mcp 0.0.5+.

Install

pip install eidetic-mcp

# Claude Code
claude mcp add eidetic -- python -m eidetic_mcp.server

# Cursor / Cline / other MCP clients use the same command in their settings
{"eidetic": {"command": "python", "args": ["-m", "eidetic_mcp.server"]}}

If the daemon is running with caller auth on, the bridge auto-discovers the token from <dataDir>/auth-token (or EIDETIC_AUTH_TOKEN env var). No bridge config change required.

Tools

query_engrams

Retrieve engrams by surface, time window, and order. surface is optional — omit to retrieve across all surfaces.

Args: surface (str, optional), limit (int, default 50, max 500), since (int64 ns), before (int64 ns), asc (bool, default false).

Returns: list of Engram objects.

search_engrams

FTS5 keyword / phrase / boolean search over payloads, ranked by relevance.

Args: q (str, required), surface (str, optional), limit (int, default 50).

Returns: list of Engram with snippet populated (v0.0.4+).

recent_engrams

Newest engrams across all surfaces, newest-first. Use for "what happened lately" without a keyword.

Args: limit (int, default 50, max 500), since (int64 ns), before (int64 ns).

count_engrams

Fast count without fetching rows. Returns {"count": N}.

Args: surface (str, optional), since (int64 ns, optional).

get_engram_by_id

Point lookup by primary key. Returns the Engram or raises if not found.

Args: id (int, required).

delete_engram_by_id

Surgical removal of a single engram. Use to scrub captured secrets or dedup relay noise.

Args: id (int, required).

insert_engram

Direct API-side insert; bypasses the fsnotify capture path. Useful for injection from mobile, webhooks, relay pipelines.

Args: surface (str, required), payload (str, required), ts (int64 ns, optional).

Returns: {"id": N}.

insert_engrams_batch

Bulk atomic insert; one transaction, one round-trip. 32 MiB body cap.

Args: engrams (list of {surface, payload, ts?}).

Returns: {"inserted": N}.

purge_engrams

Bulk delete by surface, optionally bounded by timestamp.

Args: surface (str, required), before (int64 ns, optional).

Returns: {"deleted": N}.

list_surfaces

Map of every active surface to its engram count. Live view of what the daemon has seen.

Args: none.

Returns: {"claude_code": 274203, "cursor": 4135, ...}.

daemon_status

Liveness probe — wraps GET /healthz.

Returns: {"status": "ok"}.

daemon_metrics

Wraps GET /metrics (JSON variant). Use for dashboards or to surface engram stats into a Claude Code conversation.

Returns: the full metrics JSON (version, uptime, counts per surface, query latency percentiles, update-available flag).

nucleus_ask

The killer tool. RAG over your local engrams: extracts keywords from a natural-language question, FTS5-retrieves top-K via the daemon, returns them wrapped in answer-scaffolding for the host LLM. Your engrams never leave your machine.

Args: question (str, required), surface (str, optional), limit (int, default 10).

Returns: {question, fts_query, instructions, engrams}. The host LLM (Claude / Cursor / Cline) reads the engrams and synthesizes the answer.

See nucleus_ask recipes for 5 copy-paste setups across Claude Code, Cursor, Cline, CLI, and the web dashboard.

Why a separate bridge?

Process-isolation. The daemon is Go; the MCP bridge is Python. If the Python MCP stack crashes mid-session, your engrams keep capturing. If the daemon's writer pool stalls, the MCP bridge surfaces the error cleanly without taking down the Claude Code session.

Practically: the bridge is a thin HTTP client over the daemon's UDS API (TCP on Windows). Every MCP tool call maps to one daemon endpoint. No duplicate state, no second source of truth.

Chunked-record reassembly

When a captured record exceeds 7 MiB, the daemon splits it into N chunks sharing a chunk_id in meta. The MCP bridge reassembles chunked records into ONE logical engram before returning them to the host LLM — callers never see fragmented payloads. See ADR-018 in the source repo for the meta-encoding contract.