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.7.5'

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

# 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). The current release is listed in Versioning and SDK compatibility; if you run an older one, see Upgrading.

Verify it's on your PATH:

cortexdb-mcp --version     # cortexdb-mcp 0.8.0
cortexdb-mcp --help

The binary takes two options. --transport accepts only stdio (there is no HTTP/SSE transport), and --tool-profile all|code selects the tool surface — see Tool profiles.

Setup

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

Option A — CortexDB Cloud

Create an API token on your dashboard, which also shows your actor and default scope, and give the server all four:

{
  "mcpServers": {
    "cortexdb": {
      "command": "cortexdb-mcp",
      "env": {
        "CORTEXDB_URL":     "https://api.cortexdb.ai",
        "CORTEXDB_API_KEY": "<your API token>",
        "CORTEXDB_ACTOR":   "user:acct_42",
        "CORTEXDB_SCOPE":   "org:acct_42/user:acct_42"
      }
    }
  }
}

The token lasts 90 days; replace it with a new one from the dashboard. Every tool call counts against your plan. With no CORTEXDB_API_KEY the server tries an anonymous POST /v1/auth/signup against CORTEXDB_URL instead; CortexDB Cloud has signup off (its accounts come from cortexdb.ai), and a self-hosted server only allows it with its dev minter on, so set the key.

Option B — Bring your own token (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).
• CORTEXDB_ACTOR — The actor id; must match the token's sub claim. Sent as X-Cortex-Actor on every call.
• CORTEXDB_SCOPE — The default scope path tools use when one isn't passed explicitly. Optional when signup supplied one; otherwise required (a tool call without a scope fails with no scope configured; it does not fall back to the actor).

Option C — Self-hosted server

Point CORTEXDB_URL at your server and supply the server's key as the bearer. CORTEXDB_SCOPE is required here (a self-hosted server normally has no signup to derive one from); a tool call without a scope fails with no scope configured.

{
  "mcpServers": {
    "cortexdb": {
      "command": "cortexdb-mcp",
      "env": {
        "CORTEXDB_URL":     "http://localhost:3141",
        "CORTEXDB_API_KEY": "<the server's CORTEX_API_KEY value>",
        "CORTEXDB_ACTOR":   "user:alice",
        "CORTEXDB_SCOPE":   "user:alice"
      }
    }
  }
}

On a server started with CORTEX_INSECURE_NO_AUTH=1, omit CORTEXDB_API_KEY (no Authorization header is sent; the server serves each request as the X-Cortex-Actor the MCP server sends from CORTEXDB_ACTOR, or user:local without one) but keep CORTEXDB_SCOPE. See Self-hosting defaults and the authorization note on presets.

Local state

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

• macOS / Linux: $XDG_CONFIG_HOME/cortexdb-mcp/state.json (default ~/.config/cortexdb-mcp/state.json)
• Windows: %APPDATA%\cortexdb-mcp\state.json

The file is mode 0600 on POSIX. Contents: { "token", "actor", "scope", "expires_at" } — the values POST /v1/auth/signup returned (user_id is stored as actor; expires_at when the mint reported one, used to sign up again on expiry). No memories are stored locally. It is only read when CORTEXDB_API_KEY is unset; an explicit env key always wins. Delete the file to force a re-signup on the next call.

Per-client configuration

The JSON blocks below show a token in the env block (Options A and B). For a self-hosted server use the Option C env block instead.

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 --transport stdio \
  -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... \
  cortexdb -- cortexdb-mcp

Options go before the server name and -- separates Claude Code's flags from the server command. Add --scope user to make the server available in every project, or --scope project to write it to a shareable .mcp.json in the repository root. Without --scope, Claude Code stores the entry in ~/.claude.json (local scope, this project only); there is no ~/.claude/mcp.json. To edit by hand, put the same mcpServers block into .mcp.json (project) or ~/.claude.json (user/local).

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

The server registers 27 tools, plus 3 resources (cortexdb://health, cortexdb://episodes, cortexdb://insights) and 5 prompts.

Every tool that takes a scope accepts it as tenant_id (a legacy name — it is a v1 scope path) and falls back to CORTEXDB_SCOPE.

Memory

Deleting

Knowledge graph and beliefs

Status, usage and helpers

Code memory

Four read-only tools for the code memory plane; the server must run with CORTEX_CODE_PLANE=1 or every call returns 503 CODE_PLANE_DISABLED. Repository registration is an operator action through the API/CLI, not an MCP tool.

Resources and prompts

The server also registers three MCP resources — cortexdb://health (GET /v1/auth/whoami), cortexdb://episodes (the scope's last 50 raw events via GET /v1/events) and cortexdb://insights (the same heuristic pass as get_insights) — and five prompts: investigate_incident(topic), summarize_knowledge(topic), deployment_review(service), onboard_to_codebase(repo) and weekly_digest(tenant_id?). The prompts are plain instruction templates; they make no API calls themselves.

Tool profiles

cortexdb-mcp --tool-profile code exposes only the four code_* tools (the memory tools are removed from the listing and cannot be called). The default all exposes all 27. Resources and prompts are registered under both profiles.

Configuration Reference

The wheel also carries a small FastAPI app (uvicorn cortexdb_mcp.api:app) that serves the insights pass as GET /api/insights for a dashboard. It is not part of the MCP surface.

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.