cortexdb-mcp 0.3.2

MCP Server for CortexDB — expose memory operations to AI agents

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

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).

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

Tool	Maps to	Description
memory_store	POST /v1/experience	Store a new memory. Source/tags/type become labels.
memory_search	POST /v1/recall	Search memories using natural language.
memory_forget	POST /v1/forget	Delete memories. With query, narrows by subject.
get_context	POST /v1/recall (holistic)	Deep context with facts + beliefs.
advanced_search	POST /v1/recall + temporal	Search with structured filters (time / source / type).

Event CRUD

Tool	Maps to	Description
memory_list	GET /v1/events	List events in scope, paginated.
memory_get	GET /v1/events/{id}	Fetch a single event (used for citations).
memory_delete	POST /v1/forget (memory_ids)	Delete one event by id.
memory_bulk_delete	POST /v1/forget or /v1/erasures/preview	Bulk delete with dry-run support.

Knowledge Graph (facts-backed in v1)

Tool	Maps to	Description
entity_list	GET /v1/facts	List fact subjects, ranked by count.
entity_get	GET /v1/facts?subject=…	Fact lineage for a subject.
entity_edges	GET /v1/facts?subject=…	Predicate/object pairs for an entity.
entity_link	POST /v1/experience	Store a sentence the extractor will turn into a fact.

Admin & Observability

Tool	Maps to	Description
health_check	GET /v1/auth/whoami	Verify the bearer + reach the deployment policy.
get_usage	GET /v1/auth/whoami + headers	Tier, rate limit, token expiry.
get_insights	(in-process)	Proactive insights derived from stored episodes.

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:

Resource URI	Description
cortexdb://health	Server health status
cortexdb://metrics	Request metrics (total, active, errors, rate-limited)
cortexdb://usage	Usage statistics and tier limits
cortexdb://episodes	Recent 50 episodes
cortexdb://entities	Top 100 knowledge graph entities
cortexdb://insights	Proactive insights
cortexdb://ontology	Entity and relationship type schema

Prompts

Pre-built prompt templates:

Prompt	Description
investigate_incident	Investigate an incident using stored memories
summarize_knowledge	Summarize everything known about a topic
deployment_review	Pre-deployment safety review
onboard_to_codebase	Onboard to a codebase using stored knowledge
weekly_digest	Generate a weekly activity summary

Configuration

Environment Variable	Default	Description
CORTEXDB_URL	https://api-v1.cortexdb.ai	CortexDB server URL
CORTEXDB_API_KEY	(none)	API key for authentication
CORTEXDB_TIMEOUT	30.0	HTTP request timeout (seconds)

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