@connordb/mcp-server

MCP server for ConnorDB — the system of record for agent memory.

Gives any MCP client (Claude Desktop, Cursor, Claude Code, any agent that speaks MCP) direct access to a running ConnorDB engine: hybrid search, document retrieval, time-travel reads, audit log tail. No glue code; no REST plumbing required.

Why it matters

A LangChain / LlamaIndex retriever lives inside the calling process. An MCP server lives outside the agent and is automatically discovered by the LLM client. The same connector that gives Claude Code a ConnorDB tool gives Cursor and Claude Desktop the same tool — one registration, every MCP-capable client.

If an agent team's shared memory lives in ConnorDB, install this once and every agent that points its MCP client at it gets the same hybrid-search + audit + time-travel primitives that the production engine exposes.

Quickstart — Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "connordb": {
      "command": "npx",
      "args": ["-y", "@connordb/mcp-server"],
      "env": {
        "CONNORDB_TARGET": "localhost:50051",
        "CONNORDB_API_KEY": "your-key-here"
      }
    }
  }
}

Restart Claude Desktop. The tool palette now shows search_hybrid, get_document, insert_document, wait_for_embed, list_collections, get_document_asof, audit_recent.

Quickstart — Cursor

Cursor settings → MCP → Add new MCP server with the same JSON.

Quickstart — Claude Code

Claude Code reads ~/.claude.json (or .claude/settings.json in a project). Add:

{
  "mcpServers": {
    "connordb": {
      "command": "npx",
      "args": ["-y", "@connordb/mcp-server", "--ephemeral"]
    }
  }
}

For an existing engine, keep args as ["-y", "@connordb/mcp-server"] and set CONNORDB_TARGET / CONNORDB_API_KEY in env.

Tools surface

| Tool | What it does | Use when | |------|--------------|----------| | search_hybrid | RRF over BM25 + dense + sparse in one call. The default retrieval primitive. | Default for any "find X in memory" question. | | get_document | O(1) hash lookup by id. Returns full row + payload. | Agent has an id and wants the row. | | insert_document | Atomic insert/upsert of row + payload + caller-supplied vector. Text and embedding projections can advance asynchronously; use the watermarks below when freshness matters. | Agent is adding new knowledge to the engine. | | wait_for_embed | Block until the embed worker catches up to an LSN. | After an insert_document without embedding, before a vector or hybrid search that should include the new doc. | | list_collections | Enumerate typed collections + schemas + counts. | Agent needs to know what shape of data is available. | | get_document_asof | Time-travel read at a given LSN. | "What did this doc look like before the change?" | | audit_recent | Tail of the SHA-256-chained audit log. | Compliance / debugging / "did the agent do X?" | | cluster_topology | ADR 0016 Phase 7 — whole-cluster snapshot: epoch, leader, per-member view (id, addr, in_sync, last_ack_lsn). Requires cluster_target = the cluster-internal host:port (--cluster-port). | Agent needs to know which node is the current leader, which followers are caught up, or whether a quorum exists at all. | | record_tool_call | ADR 0017 Phase A — tamper-evident record of an external tool invocation. The engine does not execute tools; this persists the agent's declaration so traceback can walk it later. Returns the LSN of the ToolCall causal frame. | Agent just called an external tool (web search, code interpreter, etc.) and wants the call durably linked to the memory it produced. | | record_decision | ADR 0017 Phase A — agent decision with verified citations. Unknown, future, or cross-tenant citations are rejected with the engine's uniform not-found semantics; the cited set is hash-bound into the per-tenant SHA-256 audit chain. | Agent has reached a conclusion and wants to record it with the evidence (cited LSNs) it relied on. | | traceback | ADR 0017 Phase A — walk the citation graph rooted at root_lsn breadth-first. Returns nodes (every reachable Read / ToolCall / Decision) plus directed edges (cites + result_of). | Operator or another agent asks "why did the swarm decide X at LSN L"; one RPC returns the full reasoning subgraph. | | endorse_row | ADR 0018 Phase A — durably endorse another agent's row. Idempotent on (target_lsn, caller_agent_id); self-endorse rejected; cross-tenant target rejected. | A second agent observes the same fact and wants to mark it team-validated instead of writing a near-duplicate row. | | dispute_row | ADR 0018 Phase A — durably dispute another agent's row with a free-form reason. Sticky: the row is NEVER overwritten, both claim and dispute coexist. Reason capped at 1024 bytes. | An agent disagrees with another agent's memory and wants the contention itself to be a first-class team signal. | | list_disputes | ADR 0018 Phase C — paginated open-dispute listing. Admin/operator keys see all tenant disputes; agent keys see participant disputes. | An agent needs the current contradiction queue before resolving or escalating. | | resolve_dispute | ADR 0018 Phase C — admin/operator-only resolution of an open dispute. Records target_lsn -> keep_lsn durably and leaves both rows intact. | An operator agent has selected the row LSN the tenant memory should keep as authoritative. | | set_storage_mode | OPERATOR-STYLE — ADR 0019 Phase B: switch the tenant between rowstore (default) and dual. dual mirrors every write into a continuous-field projection. | A tenant is opting into the continuous-field projection (one-time per tenant). | | field_insert | ADR 0019 §4 — atomic mirrored insert into rowstore + field. Returns {row_lsn, field_lsn}. payload_b64 carries the opaque blob whose digest drives the deformation. | Agent is writing into a dual-mode tenant and wants both projections to advance. | | field_sample | ADR 0020 §4 — sample k coords from a latent-space region (anchor / anchor_lsn / tile / union / intersection / difference). Returns samples + ADR 0021 §6 aggregate quality. | Agent needs to explore the latent space around a known coord, an LSN, or a named tile. | | field_seal | OPERATOR-STYLE — ADR 0019 §4: freeze the tenant's current field epoch into an immutable seal. | An operator is closing a chapter of the field projection (e.g. snapshot before a basis evolve). | | field_evolve_basis | OPERATOR-STYLE — ADR 0019 §4: explicit audited basis relearn. | An operator decides the active basis no longer fits the data and triggers a fresh relearn. |

Total: 58 tools.

Resources surface

Documents are addressable via the URI scheme connordb://documents/{id}. Clients can pin a document as context via the @-mention flow without an explicit get_document call.

Environment variables

| Var | Required | Default | What it does | |-----|----------|---------|--------------| | CONNORDB_TARGET | yes unless ephemeral | — | gRPC target of the ConnorDB engine (host:port, e.g. localhost:50051). | | CONNORDB_API_KEY | only when auth is on | unset | API key sent as X-API-Key. | | CONNORDB_EPHEMERAL | no | false | true starts a temporary loopback engine before serving MCP. Equivalent to --ephemeral. | | CONNORDB_EPHEMERAL_MODE | no | auto | auto, binary, or docker. Auto tries connordb-server, then Docker. | | CONNORDB_ENGINE_BIN | no | connordb-server | Binary path used by ephemeral binary mode. | | CONNORDB_EPHEMERAL_PORT | no | random | Loopback port for the temporary engine. | | CONNORDB_EPHEMERAL_DATA_DIR | no | temp dir | Data directory for ephemeral binary mode; omitted temp dirs are removed on exit. | | CONNORDB_EPHEMERAL_DOCKER_IMAGE | no | connordb/engine:1.5.0 | Docker image used by ephemeral Docker mode. |

Running standalone (debug)

npm install -g @connordb/mcp-server

CONNORDB_TARGET=localhost:50051 \
CONNORDB_API_KEY=... \
connordb-mcp

Temporary local engine:

connordb-mcp --ephemeral

The server speaks JSON-RPC over stdio. To inspect what tools are advertised, pipe a tools/list request:

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \
    | CONNORDB_TARGET=localhost:50051 connordb-mcp

License

See LICENSE.md at the repo root. Same proprietary license as the engine; the MCP server is shipped for adopters to connect their existing ConnorDB engine to LLM clients.

Related

• @connordb/client — the underlying TypeScript SDK.
• examples/agent-patterns — end-to-end agent memory patterns (insert, hybrid search, realtime, LLM cache, time-travel).