Skip to content

MCP Integration

Jump to bottom
idapixl edited this page Sep 22, 2026 · 6 revisions

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", "@fozikio/cortex-engine"]
    }
  }
}

Claude Code / Cursor (Windows)

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

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

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", "@fozikio/cortex-engine"]
    }
  }
}

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

The engine ships 60 cognitive tools. Twelve are active by default — the rest are enabled per-namespace via config.

Default core set (12):

Category Tools
Write observe, wonder, speculate
Read context, query, recall, neighbors
Ops ops_append, ops_query, ops_update
System stats, feedback

Commonly enabled next: believe, reflect, digest, predict, validate, wander, dream, thread_create, thread_update, thread_resolve, threads_list, journal_write, journal_read, evolve, evolution_list.

See Tool Reference for all 60 by category.

Enabling the rest of the tools

Nothing to install — all 60 cognitive tools ship inside cortex-engine as of v1.0.0. Only the core set is active by default; the remaining categories (threads, journal, content, social, graph, maintenance, vitals, consolidation, beliefs, agents) are enabled per-namespace in your config:

npx fozikio tools     # list every tool by category
npx fozikio config    # view or edit which tools are active

Restart your MCP client after changing the active set and the new tools appear.

The @fozikio/tools-* npm packages are deprecated. They were absorbed into core at v1.0.0 and are frozen on npm — installing them adds nothing. Third-party plugin authoring is still supported; see Plugin Authoring.

Shared or remote cortex (MCP over HTTP)

Since 1.8.0, fozikio serve --rest also serves MCP over Streamable HTTP at /mcp. Each client gets its own MCP session (keyed by the mcp-session-id header) over one engine, with the same tool list as stdio.

This is the answer to the one-process-per-SQLite-file rule: a main checkout and its worktrees, or several agents on one host, point .mcp.json at one running server instead of each spawning a stdio server on the same file.

CORTEX_API_TOKEN=<token> npx fozikio serve --agent <name> --rest --port 3111   # binds 127.0.0.1
{
  "mcpServers": {
    "cortex": {
      "type": "http",
      "url": "http://127.0.0.1:3111/mcp",
      "headers": {
        "x-cortex-token": "${CORTEX_API_TOKEN}"
      }
    }
  }
}

The same config points at a hosted instance — swap the URL for your Cloud Run or Railway host. Auth is the REST token, in x-cortex-token or Authorization: Bearer. The generic /api/tools/:name blocklist does not apply to /mcp: that is an agent's own session.

See Deployment for setting up your own hosted instance.

Clone this wiki locally