MCP Server

cortexdb-mcp is a small bridge process that exposes CortexDB to any Model Context Protocol client that starts a local server: Claude Desktop, Claude Code, Cursor, Windsurf, VS Code Copilot. It speaks MCP over stdio on the person's computer and calls your CortexDB server's REST API.

Installation

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

# pipx — recommended on macOS/Linux; auto-isolates the install
pipx install --python python3.11 'cortexdb-mcp>=0.9.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). 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.9.0
cortexdb-mcp --help

The binary takes two options. --transport accepts only stdio: this package runs next to the assistant (for an HTTP endpoint, use the server's own /mcp). --tool-profile all|read|write|code (or CORTEXDB_TOOL_PROFILE) selects the tool surface; see Tool profiles. 0.9.0 is the release for CortexDB 0.14.0; against an older server the tools it adds answer 404.

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 these env vars so the server skips signup and uses the credentials you supply:

• CORTEXDB_API_KEY — The bearer credential: a person's or an agent's token minted via POST /v1/auth/tokens, or a token from your identity provider through the server's issuers file.
• CORTEXDB_ACTOR — Sent as X-Cortex-Actor. Optional since 0.9.0: left unset, it is the token's sub when that names an actor (user:, agent:, service:, system:). Set CORTEXDB_ACTOR=- for an identity provider's token whose issuer maps the subject itself; the server takes it alone.
• 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 cortexdb \
  -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-mcp

The server's name comes first: -e takes several values, so a name written after the -e flags is read as one more variable (and the command fails with missing required argument 'commandOrUrl'). Everything after -- is the server's own command line, so -- cortexdb-mcp --tool-profile write adds the write tools. 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).

For the server's own remote MCP endpoint, Claude Code takes the URL and a header instead: claude mcp add --transport http cortexdb https://memory.acme.example/mcp --header "Authorization: Bearer <token>" (Connecting AI Assistants).

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 default profile, all, lists 33 tools; write lists 35, read 26 and code 4. The server also registers 3 resources (cortexdb://health, cortexdb://episodes, cortexdb://insights) and 5 prompts. Since 0.9.0 a tool refuses an argument it does not take (it used to drop it), and every tool carries MCP annotations (readOnlyHint, destructiveHint, idempotentHint), so a client can ask before a destructive call.

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

Access, rollups, notices and the directory (0.9.0)

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

Select one with --tool-profile or CORTEXDB_TOOL_PROFILE. A tool outside the profile is removed from the listing and cannot be called. Resources and prompts are registered under every profile.

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.