CortexDB MCP Server

MCP (Model Context Protocol) server that gives AI tools persistent long-term memory via CortexDB. Works with Claude Desktop, Cursor, Windsurf, VS Code Copilot, and any MCP-compatible client.

0.3.0 rewrites the server against the v1 CortexDB API. Default surface is now https://api-v1.cortexdb.ai. The server auto-signs-up anonymously on first launch — no API key required.

What's new in 0.9.0 for CortexDB 0.14.0

0.9.0 is the release for CortexDB 0.14.0, the shared-memory release: per-person and agent tokens, org trees with private regions, rollups, publishing, notices and a directory of names. It still works against an older server, where the tools it adds answer 404 (which their error says). COVERAGE.md has the audit of every tool against 0.14.0 and what each finding changed.

Breaking changes

• A tool refuses an argument it does not take. Until 0.8.0 an unknown argument was dropped: memory_forget(reason=..., memory_ids=[...]) dropped the ids and forgot every derived record in the scope, and memory_store(content=..., scope=...) wrote to the default scope. Now the call fails, names the argument and lists the ones the tool takes; every tool's schema says additionalProperties: false. CortexDB 0.14.0 refuses the same mistake on its forget and erasure routes, whose selectors are strict.
• The default profile is no longer every tool. --tool-profile all (the default) lists today's tools and the new read tools; the new write tools, publish and forget_by_key, are opt-in with --tool-profile write, as the server's own HTTP /mcp serves its writes only under CORTEX_MCP_PROFILE=write. A new read profile lists only the tools that write no memory.
• The recall tools send view only when CORTEXDB_VIEW is set. The server's default is holistic, but at a shared org-tree scope (an org, a team, a group, a compartment) a recall naming no view reads granular, and one naming holistic is refused with 422 VIEW_NOT_ALLOWED_AT_SCOPE: every search at a team scope used to fail.
• X-Cortex-Actor comes from the token when CORTEXDB_ACTOR is unset: the sub of a PASETO or JWT bearer, when it names an actor (user:, agent:, service:, system:). A minted token used to need CORTEXDB_ACTOR set by hand, else every call was 401. Set CORTEXDB_ACTOR=- for a token whose issuer maps the subject itself (an IdP's sub), which the server takes alone.
• Errors read differently. A refusal is CortexDB returned HTTP <status> <code> (retriable | not retriable) on <route>: <message>, then What to do: for each code a caller can act on, the details and the request id. It used to be the raw JSON body.
• The forget tools say what they delete. Under the server's default cascade (derived_only), memory_forget and memory_bulk_delete delete derived records (facts, beliefs, episodes, understanding) and keep the memories themselves, which their descriptions used to deny. Every forget answer shows its derived counts, how many named memories matched, its audit id and the server's warnings. To delete memories, use memory_delete (by id) or forget_by_key (by the keys they were written with).
• memory_status shows the server's advice (resend and note). By event id, "not found" means erased, forgotten or not visible to you; it no longer says re-storing is safe. A failed write is stored and excluded from recall: it says never to re-send it, at any age, under any key (its key replays the failure, and a copy under a new key would store the memory twice), since the operator re-includes the stored event in place. It used to suggest a new key.
• memory_get sends tenant_id as ?scope=, the event's exact scope (an event elsewhere answers the same 404 as a missing one), which a cluster routes the read by.
• memory_list pages by cursor, not offset. CortexDB 0.14.0 pages GET /v1/events by an opaque, newest-first cursor bound to its listing, and refuses a number (422 INVALID_CURSOR). Each page ends with More: cursor=<next>; pass it back with the same tenant_id and episode_type, which the server now filters.

New tools

New fields on existing tools, each sent only when used, so a call without them sends the 0.8.0 request (but for belief_declare, which sends a fresh idempotency_key when none is given, as memory_store does):

Every forget answer and preview says what a legal hold kept (events_under_legal_hold, derived_under_legal_hold), which no deleted count includes. A retriable refusal of memory_store or belief_declare names the idempotency key the attempt sent, so a write whose outcome is unknown (WAL_OUTCOME_UNKNOWN) is retried with it and never made twice.

Each answer of a write names where a redirected write landed (redirected_to: CortexDB 0.14.0 stores an agent's write in its person's private space when it cannot show what its run read), and health_check and get_usage name an agent token's chain. Every tool carries MCP annotations (readOnlyHint, destructiveHint, idempotentHint), so a client asks before a destructive call.

Credentials

• CORTEXDB_API_KEY takes any bearer: a person's own token, an agent's chain token (act, run), a token from an issuers-file entry (an enterprise IdP's), or the deployment's operator key (CORTEX_API_KEY on the server).
• CORTEXDB_SUBJECT_TOKEN: with the operator key, a person's or a worker's token, sent as X-Cortex-Subject-Token. The server evaluates each decision for that person too and counts what it would refuse (GET /v1/admin/access/report, check subject_shadow), without changing any answer.
• CORTEXDB_BREAK_GLASS_REASON, CORTEXDB_BREAK_GLASS_TICKET, CORTEXDB_BREAK_GLASS_NOTE: on a deployment that refuses the operator key's data reads (CORTEX_OPERATOR_DATA_READS=deny, the default on cloud_shared_saas), every request carries X-Cortex-Break-Glass: reason=<reason>; ticket=<ticket>[; note=<note>]. The reason is one of incident, legal, support, security, migration, restore or other; the ticket is your case reference (1 to 64 characters of [A-Za-z0-9._:-], no personal data); the note, at most 256 bytes, goes to the decision log only. Each such request is recorded, and a read of someone's private region tells them first (see notices). Without them such a read answers BREAK_GLASS_REQUIRED, whose error says what to set. A setting the server would refuse fails the call before anything is sent, naming the variable.
• Confined tokens. A token that carries scopes holds only the capabilities its entries name. A refusal names the capability (details.capability, details.link: confinement) and the entry to mint (<capability>:<scope>); for a recall, CORTEXDB_VIEW=granular reads with scope.read.local alone.
• CORTEXDB_PURPOSE: the purpose reads declare unless a call names its own ([a-z0-9_-], 1 to 64 characters): a roster path whose when names it holds only for such a read, and every decision line records it.

Configuration examples

Claude Desktop, a person's own token, with the write tools (claude_desktop_config.json: on macOS ~/Library/Application Support/Claude/, on Windows %APPDATA%\Claude\; Settings > Developer > Edit Config opens it, and Claude Desktop reads it only after a full quit and restart). Give literal values here, not ${VAR} references:

{
  "mcpServers": {
    "cortexdb": {
      "command": "cortexdb-mcp",
      "args": ["--tool-profile", "write"],
      "env": {
        "CORTEXDB_URL": "https://memory.example.com",
        "CORTEXDB_API_KEY": "<PASETO_TOKEN>",
        "CORTEXDB_SCOPE": "org:acme/user:alice"
      }
    }
  }
}

An operator's read-only session with break-glass, telling the people whose private regions it reads:

{
  "mcpServers": {
    "cortexdb-operator": {
      "command": "cortexdb-mcp",
      "args": ["--tool-profile", "read"],
      "env": {
        "CORTEXDB_URL": "https://memory.example.com",
        "CORTEXDB_API_KEY": "<the deployment's CORTEX_API_KEY>",
        "CORTEXDB_ACTOR": "service:support",
        "CORTEXDB_SCOPE": "org:acme",
        "CORTEXDB_VIEW": "granular",
        "CORTEXDB_BREAK_GLASS_REASON": "support",
        "CORTEXDB_BREAK_GLASS_TICKET": "SUP-1142"
      }
    }
  }
}

Claude Code, for every project of this user (--scope user, stored in ~/.claude.json; local, the default, is this project only and private to you; project writes .mcp.json for the team). The server's name comes first: -e takes several values, so a name written after it would be read as one more variable. Everything after -- is the server's own command line:

claude mcp add cortexdb --scope user \
  -e CORTEXDB_URL=https://memory.example.com \
  -e CORTEXDB_API_KEY="$CORTEXDB_API_KEY" \
  -e CORTEXDB_SCOPE=org:acme/user:alice \
  -- cortexdb-mcp --tool-profile write

Or a project's .mcp.json, checked in without the secret. Claude Code expands ${CORTEXDB_API_KEY} from the environment it was started in, so export the variable first: an unset one is passed as the literal text, with a warning in claude mcp list. Claude Code asks before it starts a project's server the first time:

{
  "mcpServers": {
    "cortexdb": {
      "command": "cortexdb-mcp",
      "args": ["--tool-profile", "write"],
      "env": {
        "CORTEXDB_URL": "https://memory.example.com",
        "CORTEXDB_API_KEY": "${CORTEXDB_API_KEY}",
        "CORTEXDB_SCOPE": "org:acme/team:eng"
      }
    }
  }
}

Quick Start

# Install (the PyPI name is `cortexdb-mcp`)
pip install cortexdb-mcp

# Then run with zero config:
cortexdb-mcp

For a coding agent that only needs repository intelligence, select the compact read-only surface (four tools: explore, impact, inventory, graph):

cortexdb-mcp --tool-profile code

This materially reduces tool-schema context while retaining natural-language retrieval, typed traversal, prefix symbol discovery, and directory inventory.

The profiles (--tool-profile, or CORTEXDB_TOOL_PROFILE):

That's it. On first launch the server hits POST /v1/auth/signup, mints a free-tier PASETO token + scope for itself, and caches them under ~/.config/cortexdb-mcp/state.json (Linux/macOS) or %APPDATA%\cortexdb-mcp\state.json (Windows). Re-launches reuse the cached identity until the token expires (7 days); the cached expires_at is checked at load, and a token the server rejects with 401 is discarded and re-minted automatically, so no hand-deletion of state.json is needed. Signup runs against any configured CORTEXDB_URL, self-hosted included; a deployment with no minter answers 503 and the server carries on unauthenticated.

To target a custom deployment or pre-existing identity, set any of:

export CORTEXDB_URL="https://api-v1.cortexdb.ai"   # base URL
export CORTEXDB_API_KEY="v4.public..."             # bearer: a token, or the operator key
export CORTEXDB_ACTOR="user:alice"                 # X-Cortex-Actor (default: the token's sub)
export CORTEXDB_SCOPE="org:acme/user:alice"        # default scope path

IDE Setup

Most clients just need a single line — the auto-signup handles the rest.

Claude Desktop

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

{
  "mcpServers": {
    "cortexdb": {
      "command": "cortexdb-mcp"
    }
  }
}

Windows note (audit POL-3): if Claude Desktop / Cursor / Windsurf can't find cortexdb-mcp on PATH, give it the full path to the installed executable:

{
  "mcpServers": {
    "cortexdb": {
      "command": "C:\\Python313\\Scripts\\cortexdb-mcp.exe"
    }
  }
}

Locate it with where cortexdb-mcp in cmd.exe or (Get-Command cortexdb-mcp).Source in PowerShell.

Some Windows terminals don't have UTF-8 enabled by default, which can garble emoji in --help output (they show as ?). The server itself isn't affected — only the CLI banner. Run chcp 65001 once per terminal session to fix.

Claude Code (CLI)

claude mcp add cortexdb -- cortexdb-mcp

Add --scope user for every project of yours, or --scope project to write the project's .mcp.json; the configuration examples above set a token and a profile. Claude Code does not read ~/.claude/mcp.json.

Cursor

Edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "cortexdb": {
      "command": "cortexdb-mcp"
    }
  }
}

Or in Cursor Settings > MCP Servers > Add Server.

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "cortexdb": {
      "command": "cortexdb-mcp"
    }
  }
}

VS Code (GitHub Copilot)

Add to .vscode/mcp.json in your project or ~/.vscode/mcp.json globally:

{
  "servers": {
    "cortexdb": {
      "command": "cortexdb-mcp"
    }
  }
}

Windows tip

On Windows, MCP clients sometimes need the absolute path:

{
  "mcpServers": {
    "cortexdb": {
      "command": "C:\\Python310\\Scripts\\cortexdb-mcp.exe"
    }
  }
}

Tools

Memory Operations

Event CRUD

Access and shared memory (CortexDB 0.14.0)

Knowledge Graph (facts-backed in v1)

Bi-temporal Conflicts & Claim History

Validity boundaries carry a basis: stated boundaries render as "since/until <date>"; observed boundaries are knowledge bounds and render as "by <date>" — never "on <date>".

Admin & Observability

Removed from 0.3.0

memory_update, export_data, import_data, get_ontology — v1 has no direct equivalents. Updates: store a new event; bulk import: see /v1/import directly with the v1 envelope shape; ontology: not part of the v1 surface.

Resources

Resources provide read-only data that AI tools can access:

Prompts

Pre-built prompt templates:

Configuration

Errors

A tool that fails returns the error as its result (isError: true):

CortexDB returned HTTP 403 BREAK_GLASS_REQUIRED (not retriable) on POST /v1/recall: the operator key's
private_region action on /v1/recall needs X-Cortex-Break-Glass under the tenant's operator mode deny
What to do: ... set CORTEXDB_BREAK_GLASS_REASON ... and CORTEXDB_BREAK_GLASS_TICKET ...
Details: class=private_region, mode=deny, route=/v1/recall
Request id: req_01a17af6-b6aa-7811-a96a-2563471d4586

retriable is the server's own flag (with Retry-After when it sends one): retry such a call unchanged. What to do covers the codes a caller can act on, among them BREAK_GLASS_REQUIRED, a confinement refusal (POLICY_DENIED with details.link: confinement, naming details.capability), VIEW_NOT_ALLOWED_AT_SCOPE, INVALID_HEADER (naming the setting behind the header: CORTEXDB_ACTOR, the break-glass settings), ACCESS_RESTORE_PENDING, NOTICE_UNAVAILABLE, FORMAT_UPGRADE_PENDING, WAIT_TIMEOUT, CONSISTENCY_TOKEN_INVALID, WAL_OUTCOME_UNKNOWN (with the idempotency key to retry with), IDEMPOTENCY_CONFLICT, DB_TIMEOUT, ROLLUP_SUPERSEDED (naming the current build), INVALID_CURSOR, CLUSTER_ROUTE_UNSUPPORTED, ACCESS_LIMIT_REACHED, SUBJECT_UNMAPPED, PUBLISH_PERSON_REQUIRED, FRESH_AUTH_REQUIRED, SCOPE_MOVING and the token codes (act_not_delegable among them). The client keeps no table of statuses or retriable flags: a code it does not know is read by its status and the envelope's retriable.

Examples

Store a memory from Cursor

Ask your AI assistant:

"Remember that the payments service was migrated to Stripe v3 on March 15th"

The assistant will call memory_store with the content.

Search memories

"What do we know about the payments service?"

The assistant calls memory_search and gets relevant context from CortexDB.

Explore the knowledge graph

"Show me all entities related to the auth service"

The assistant calls entity_get or entity_edges to traverse relationships.

Pre-deployment review

"Run a deployment review for the user-service"

Uses the deployment_review prompt to check for recent incidents, dependencies, and risks.

Architecture

┌─────────────┐     stdio/SSE     ┌──────────────┐     HTTP     ┌──────────┐
│  AI Client  │ ◄──────────────► │  MCP Server  │ ◄──────────► │ CortexDB │
│  (Cursor,   │     MCP JSON-RPC  │  (this pkg)  │   REST API   │  Server  │
│   Claude,   │                   │              │              │          │
│   VS Code)  │                   └──────────────┘              └──────────┘
└─────────────┘

The MCP server is a thin translation layer:

1. Receives MCP tool calls from the AI client
2. Translates them to CortexDB REST API calls
3. Formats responses for the AI to consume

Tests

pip install -e ".[test]"
python -m pytest -q        # unit tests, and the stdio protocol against a local stub
python tests/live/live_stdio.py --binary /path/to/cortexdb --port 3430

The live test starts a real CortexDB release binary on a fresh data directory, registers a small org tree, mints person, confined and agent tokens, and drives cortexdb-mcp over stdio with the official MCP client, calling every tool of every profile. It stops the server when it is done.

License

MIT