MCP Integration

MCP Integration

cortex-engine runs as an MCP (Model Context Protocol) server, giving any MCP-compatible AI client access to persistent memory.

Supported Clients

• Claude Code (CLI)
• Claude Desktop
• Cursor
• Windsurf
• Any client implementing the MCP specification

Quick Setup

The fastest path: run npx fozikio init my-agent and open the directory in your MCP client. It generates a .mcp.json that works immediately.

Manual Configuration

Claude Code / Cursor (macOS/Linux)

Add to .mcp.json in your project root:

{
  "mcpServers": {
    "cortex": {
      "command": "npx",
      "args": ["-y", "cortex-engine@0.6.0"]
    }
  }
}

Claude Code / Cursor (Windows)

Windows requires the cmd /c wrapper to avoid spawn npx ENOENT errors:

{
  "mcpServers": {
    "cortex": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "cortex-engine@0.6.0"]
    }
  }
}

Note: fozikio init generates the correct config for your platform automatically.

Claude Desktop

Add to claude_desktop_config.json (same platform rules as above):

{
  "mcpServers": {
    "cortex": {
      "command": "npx",
      "args": ["-y", "cortex-engine@0.6.0"]
    }
  }
}

With Firestore (cloud storage)

{
  "mcpServers": {
    "cortex": {
      "command": "npx",
      "args": ["cortex-engine"],
      "env": {
        "GCP_PROJECT_ID": "your-project-id",
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/credentials.json"
      }
    }
  }
}

Scoped to a specific agent

{
  "mcpServers": {
    "cortex": {
      "command": "npx",
      "args": ["cortex-engine", "--agent", "researcher"]
    }
  }
}

Available Tools

Once connected, your agent has access to 25 core tools:

Category	Tools
Write	observe, wonder, speculate, believe, reflect, digest
Read	query, recall, predict, validate, neighbors, wander
Threads	thread_create, thread_update, thread_resolve, threads_list
Ops	ops_append, ops_query, ops_update
Identity	evolve, evolution_list, journal_write, journal_read
System	stats, dream

Plugins add more tools automatically when installed. See Tool Reference for details.

Plugins

Install plugins and cortex auto-discovers them:

npm install @fozikio/tools-threads @fozikio/tools-journal @fozikio/tools-vitals

No config changes needed. Restart your MCP client and the new tools appear.

Available plugins:

• @fozikio/tools-threads — thought threads
• @fozikio/tools-journal — session journaling
• @fozikio/tools-content — content pipeline
• @fozikio/tools-evolution — identity evolution
• @fozikio/tools-social — social cognition
• @fozikio/tools-graph — graph analysis
• @fozikio/tools-maintenance — memory maintenance
• @fozikio/tools-vitals — health metrics
• @fozikio/tools-reasoning — cognitive reasoning

Remote Cortex (Cloud Run)

Instead of running cortex locally, you can connect to a hosted instance:

{
  "mcpServers": {
    "cortex": {
      "type": "sse",
      "url": "https://your-cortex-service.run.app/mcp",
      "headers": {
        "x-cortex-token": "your-api-token"
      }
    }
  }
}

See Deployment for setting up your own hosted instance.