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.

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.

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..."             # PASETO bearer token
export CORTEXDB_ACTOR="user:alice"                 # ActorId, sent as X-Cortex-Actor
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)

Edit ~/.claude/mcp.json:

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

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

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

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

License

MIT