Claude Desktop

Connect Cortexa to Claude Desktop via MCP so your desktop assistant can search, capture, and recall your knowledge base.

Prerequisites

• Cortexa desktop app running with the HTTP API enabled (default: http://127.0.0.1:7373)
• Your bearer token from Settings → External in the Cortexa app
• The cortexa-mcp stdio bridge binary (Claude Desktop only supports stdio MCP)

Get the stdio Bridge

Claude Desktop does not support HTTP MCP transports, so you need the standalone cortexa-mcp stdio bridge.

Download it (no Rust toolchain needed): grab the build for your platform from the latest release — e.g. cortexa-mcp-aarch64-apple-darwin (Apple Silicon), cortexa-mcp-x86_64-apple-darwin (Intel Mac), cortexa-mcp-x86_64-pc-windows-msvc.exe (Windows x64), cortexa-mcp-aarch64-pc-windows-msvc.exe (Windows ARM). On macOS, chmod +x it and point the config at wherever you saved it.

Or build it from source:

cargo build -p cortexa-mcp --release

The binary lands at:

Platform	Path
Windows	target\release\cortexa-mcp.exe
macOS	target/release/cortexa-mcp

Configure Claude Desktop

Edit the Claude Desktop configuration file. The location depends on your platform:

Platform	Config path
Windows	%APPDATA%\Claude\claude_desktop_config.json
macOS	~/Library/Application Support/Claude/claude_desktop_config.json

If the file does not exist, create it.

Windows

{
  "mcpServers": {
    "cortexa": {
      "command": "C:\\Users\\YourName\\path\\to\\target\\release\\cortexa-mcp.exe",
      "env": {
        "CORTEXA_URL": "http://127.0.0.1:7373",
        "CORTEXA_TOKEN": "<TOKEN>"
      }
    }
  }
}

Replace C:\\Users\\YourName\\path\\to\\target\\release\\cortexa-mcp.exe with the actual absolute path to your built binary. Use double backslashes in the JSON.

macOS

{
  "mcpServers": {
    "cortexa": {
      "command": "/Users/yourname/path/to/target/release/cortexa-mcp",
      "env": {
        "CORTEXA_URL": "http://127.0.0.1:7373",
        "CORTEXA_TOKEN": "<TOKEN>"
      }
    }
  }
}

Replace /Users/yourname/path/to/target/release/cortexa-mcp with the actual absolute path to your built binary.

Using the CLI config instead of env vars

The bridge also reads credentials from the CLI config file. If you have already run:

cortexa-cli config --url http://127.0.0.1:7373 --token <TOKEN>

Then you can omit the env block:

{
  "mcpServers": {
    "cortexa": {
      "command": "C:\\Users\\YourName\\path\\to\\target\\release\\cortexa-mcp.exe"
    }
  }
}

Environment variables take precedence over the CLI config file when both are set.

Restart Claude Desktop

After saving the config file, fully quit and relaunch Claude Desktop. The cortexa_* tools will appear in the tools list (the hammer icon in the chat input area).

Available Tools

Once connected, Claude Desktop has access to the Cortexa MCP tools (full list in the MCP Tools reference), including:

Tool	Purpose
cortexa_ingest	Capture text into the encrypted store
cortexa_capture	Structured capture with metadata (thought type, project, tags, etc.)
cortexa_search	Hybrid keyword + semantic search
cortexa_recent	List most recent captures
cortexa_context	Ambient context brief for current work
cortexa_think	Trigger the Deep Think pipeline on an item
cortexa_brief	Retrieve the structured brief after Deep Think
cortexa_health	Confirm the app is reachable
cortexa_sync_context	Generate .cortexa-context.md for zero-prompt context injection

Usage Examples

Once configured, you can interact naturally:

• "What have I captured about the auth system?" — Claude searches your vault via cortexa_search
• "Save this: decided to use Redis for session caching because..." — Claude captures via cortexa_capture
• "What were my recent thoughts?" — Claude calls cortexa_recent
• "Analyze this thought more deeply" — Claude triggers cortexa_think and later retrieves the brief

Adding to an Existing Config

If you already have other MCP servers configured, add the cortexa key inside the existing mcpServers object:

{
  "mcpServers": {
    "existing-server": { "...": "..." },
    "cortexa": {
      "command": "C:\\path\\to\\cortexa-mcp.exe",
      "env": {
        "CORTEXA_URL": "http://127.0.0.1:7373",
        "CORTEXA_TOKEN": "<TOKEN>"
      }
    }
  }
}

Troubleshooting

Tools don't appear after restart — Open the Claude Desktop developer console (Help → Toggle Developer Tools) and check for MCP connection errors. Verify the binary path exists and is correct.

"Cortexa app isn't reachable" errors — Make sure the Cortexa desktop app is running. The HTTP API starts automatically when the app launches. The bridge forwards every tool call to the app's /mcp endpoint; while the app is down only cortexa_capture still works (it buffers locally and syncs later). If Claude Desktop started before the app and shows no Cortexa tools, restart Claude Desktop once the app is up.

423 Locked responses — The vault is locked via idle lock. Unlock the Cortexa app by entering your passphrase.

Binary not found — Double-check the path in the config. On Windows, make sure you're using double backslashes (\\) in the JSON path.

Project continuity

Enable Search -> Traceable context for agents in Cortexa, then follow the session-start and handoff workflow. Call cortexa_context with the project at session start, verify current state, and leave a structured cortexa_capture handoff before stopping. Captured check results remain caller reports; exported context files are snapshots and should be refreshed before reuse.