MCP Server

The CortexDB MCP server is a small bridge process that exposes CortexDB to any Model Context Protocol–compatible client — Claude Desktop, Claude Code, Cursor, Windsurf, VS Code Copilot.

Installation

# pip (any Python 3.10+ venv)
pip install 'cortexdb-mcp>=0.6.0'

# pipx — recommended on macOS/Linux; auto-isolates the install
pipx install --python python3.11 'cortexdb-mcp>=0.6.0'

# uv — fastest; pulls its own Python if needed
uvx --python 3.11 cortexdb-mcp --help

The PyPI package is cortexdb-mcp, not cortexdbai-mcp (which does not exist on PyPI). Pin >=0.6.0 (current release: 0.7.4). 0.2.x releases targeted retired v0 endpoints (/v1/remember, /v1/recall_memories) which today's API no longer routes — they 404 on every tool call (verified). See Versioning and SDK compatibility.

Verify it's on your PATH:

cortexdb-mcp --help

Setup

Every MCP client uses a JSON config file. The structure is the same everywhere — only the file path differs. There are two ways to set it up.

Option A — Zero-config (anonymous, free tier)

Just point your client at the binary with no env block. On first launch the server posts to POST /v1/auth/signup, mints an anonymous PASETO bearer + actor + scope, and persists them locally (see Local state). Every subsequent call reuses that identity.

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

This is the recommended path for trying CortexDB. The token has a 7-day TTL; the server refreshes by re-signing-up before expiry.

Option B — Bring your own token (paid tier or your own IdP)

Set three env vars so the server skips signup and uses the credentials you supply:

• CORTEXDB_API_KEY — The bearer credential: a PASETO v4 token minted via POST /v1/auth/tokens (or by your IdP), or — on a self-hosted server — the server's CORTEX_API_KEY value itself.
• CORTEXDB_ACTOR — The actor id; must match the token's sub claim. Sent as X-Cortex-Actor on every call.
• CORTEXDB_SCOPE — (optional) The default scope path tools use when one isn't passed explicitly. Defaults to the actor.

Override the endpoint with CORTEXDB_URL if you self-host — http://localhost:3141 for a local server (default: https://api-v1.cortexdb.ai).

Local state

The server stores its credentials (and only its credentials) under:

• macOS / Linux: ~/.config/cortexdb-mcp/state.json
• Windows: %APPDATA%\cortexdb-mcp\state.json

The file is mode 0600 on POSIX. Contents: {token, user_id, scope, expires_at} — exactly what POST /v1/auth/signup returned, ~1 KB. No memories are stored locally. Delete the state file to force a re-signup on next launch.

Per-client configuration

The JSON blocks below show Option B (bring-your-own-token). For Option A, drop the env block — just "command": "cortexdb-mcp" and the server handles signup itself on first launch.

Claude Desktop

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "cortexdb": {
      "command": "cortexdb-mcp",
      "env": {
        "CORTEXDB_API_KEY": "v4.public.eyJpc3MiOi...",
        "CORTEXDB_ACTOR":   "user:u_019e2f...",
        "CORTEXDB_SCOPE":   "org:u_019e2f.../user:u_019e2f..."
      }
    }
  }
}

Claude Code (CLI)

claude mcp add cortexdb cortexdb-mcp \
  -e CORTEXDB_URL=https://api-v1.cortexdb.ai \
  -e CORTEXDB_API_KEY=v4.public... \
  -e CORTEXDB_ACTOR=user:u_019e... \
  -e CORTEXDB_SCOPE=org:u_019e.../user:u_019e...

Or edit ~/.claude/mcp.json directly with the same env block.

Cursor

Edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "cortexdb": {
      "command": "cortexdb-mcp",
      "env": {
        "CORTEXDB_URL":     "https://api-v1.cortexdb.ai",
        "CORTEXDB_API_KEY": "v4.public...",
        "CORTEXDB_ACTOR":   "user:u_019e...",
        "CORTEXDB_SCOPE":   "org:u_019e.../user:u_019e..."
      }
    }
  }
}

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json (same mcpServers block as Cursor).

VS Code (GitHub Copilot)

Add to .vscode/mcp.json (project) or ~/.vscode/mcp.json (global). Note the key is servers, not mcpServers:

{
  "servers": {
    "cortexdb": {
      "command": "cortexdb-mcp",
      "env": {
        "CORTEXDB_URL":     "https://api-v1.cortexdb.ai",
        "CORTEXDB_API_KEY": "v4.public...",
        "CORTEXDB_ACTOR":   "user:u_019e...",
        "CORTEXDB_SCOPE":   "org:u_019e.../user:u_019e..."
      }
    }
  }
}

Tools exposed

0.7.4 ships 22 tools, mapped to v1 endpoints as follows:

v0.2.x exposed a different 13-tool set against legacy endpoints (/v1/remember, /v1/admin/health) which today's API no longer routes — those clients 404 on every call. Pin cortexdb-mcp>=0.6.0. Future versions may add tools for /v1/answer, /v1/understanding/synthesize and other v1 endpoints — track the server.py decorator list for the source of truth.

Configuration Reference

Architecture

Your Machine                           CortexDB
┌──────────┐    stdio     ┌───────────┐    HTTPS    ┌──────────┐
│ Cursor / │ ◄─────────►  │ cortexdb- │ ◄─────────► │  v1 API  │
│ Claude / │  MCP JSON    │    mcp    │  REST       │  server  │
│ VS Code  │              │ (bridge)  │             │          │
└──────────┘              └───────────┘             └──────────┘

The bridge process holds the bearer token in memory, injects Authorization and X-Cortex-Actor headers on every call, and translates MCP tool invocations into v1 HTTP requests. Nothing is stored locally except the credentials.

Next steps

• Python SDK — programmatic access, V1Client + AsyncV1Client.
• TypeScript SDK — Node.js and browser apps, V1Client.signup() one-liner.
• Auth — how tokens, actors, and capabilities fit together.
• API Reference — endpoint-by-endpoint reference.