MCP Server

CortexDB includes a Model Context Protocol (MCP) server that exposes memory operations as tools for AI assistants. This lets Claude Desktop, Cursor, Windsurf, and other MCP-compatible clients use CortexDB directly.

Installation

pip install cortexdb[mcp]

Or install the standalone MCP server:

npm install -g @cortexdb/mcp-server

Claude Desktop Setup

Add to your Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "cortexdb": {
      "command": "cortexdb-mcp",
      "args": ["--base-url", "http://localhost:8080"],
      "env": {
        "CORTEX_API_KEY": "your-api-key",
        "CORTEX_DEFAULT_TENANT": "my-app"
      }
    }
  }
}

Using Python

{
  "mcpServers": {
    "cortexdb": {
      "command": "python",
      "args": ["-m", "cortexdb.mcp"],
      "env": {
        "CORTEX_BASE_URL": "http://localhost:8080",
        "CORTEX_API_KEY": "your-api-key",
        "CORTEX_DEFAULT_TENANT": "my-app"
      }
    }
  }
}

Cursor Setup

In Cursor settings, add an MCP server:

1. Open Settings > MCP Servers
2. Add a new server:
   • Name: cortexdb
   • Command: cortexdb-mcp
   • Args: --base-url http://localhost:8080
   • Env: CORTEX_API_KEY=your-api-key

Windsurf Setup

Add to your Windsurf MCP configuration:

{
  "mcpServers": {
    "cortexdb": {
      "command": "cortexdb-mcp",
      "args": ["--base-url", "http://localhost:8080"],
      "env": {
        "CORTEX_API_KEY": "your-api-key",
        "CORTEX_DEFAULT_TENANT": "my-app"
      }
    }
  }
}

Available Tools

The MCP server exposes these tools:

cortexdb_remember

Store an episode in memory.

| Parameter | Type | Required | Description | |---|---|---|---| | content | string | Yes | Content to remember | | type | string | No | Episode type (default: message) | | source | string | No | Source identifier | | tenant_id | string | No | Tenant (uses default if unset) | | namespace | string | No | Namespace | | metadata | object | No | Additional metadata |

cortexdb_recall

Retrieve relevant memories.

| Parameter | Type | Required | Description | |---|---|---|---| | query | string | Yes | Natural language query | | top_k | number | No | Max results (default: 10) | | tenant_id | string | No | Tenant | | namespace | string | No | Namespace | | episode_type | string | No | Filter by type |

cortexdb_forget

Remove memories from results.

| Parameter | Type | Required | Description | |---|---|---|---| | memory_id | string | Yes | Episode ID to forget | | tenant_id | string | No | Tenant |

cortexdb_search

Search for episodes.

| Parameter | Type | Required | Description | |---|---|---|---| | query | string | Yes | Search query | | mode | string | No | keyword, vector, or hybrid | | top_k | number | No | Max results | | tenant_id | string | No | Tenant |

cortexdb_entities

List or get entities.

| Parameter | Type | Required | Description | |---|---|---|---| | entity_id | string | No | Get specific entity | | entity_type | string | No | Filter by type | | tenant_id | string | No | Tenant |

Configuration

| Environment Variable | Default | Description | |---|---|---| | CORTEX_BASE_URL | http://localhost:8080 | CortexDB server URL | | CORTEX_API_KEY | (none) | API key | | CORTEX_DEFAULT_TENANT | (none) | Default tenant ID | | CORTEX_DEFAULT_NAMESPACE | (none) | Default namespace | | CORTEX_MCP_LOG_LEVEL | info | Log level |

Usage Example

Once configured, your AI assistant can use CortexDB tools in conversation:

You: Remember that we decided to use Rust for the backend rewrite. The main reasons were performance and memory safety.

Assistant: [calls cortexdb_remember with type="decision"] Stored that decision in memory.

You: What language did we pick for the backend?

Assistant: [calls cortexdb_recall with query="backend language choice"] Based on your team's memories, you decided to use Rust for the backend rewrite. The main reasons were performance and memory safety.

Next Steps