Claude Code

Set up Cortexa as an MCP server for Claude Code to give your CLI agent persistent memory and contextual awareness across coding sessions.

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
• Claude Code installed (npm install -g @anthropic-ai/claude-code or via the official installer)

Option A — HTTP Transport (Recommended)

The Cortexa desktop app serves MCP natively at POST http://127.0.0.1:7373/mcp using the Streamable HTTP transport. No extra binary needed.

Run this command in your terminal:

claude mcp add --transport http cortexa http://127.0.0.1:7373/mcp \
  --header "Authorization: Bearer <TOKEN>"

Replace <TOKEN> with the bearer token from Settings → External.

That's it. The 10 cortexa_* tools are now available in every Claude Code session.

Option B — stdio Transport

If you prefer to use the standalone stdio bridge binary instead of HTTP, you need the cortexa-mcp binary.

Download it (no Rust toolchain needed): grab the build for your platform from the latest release — cortexa-mcp-<target> (e.g. cortexa-mcp-aarch64-apple-darwin, cortexa-mcp-x86_64-pc-windows-msvc.exe). On macOS/Linux chmod +x it.

Or build it from source:

cargo build -p cortexa-mcp --release
# binary lands at target/release/cortexa-mcp.exe (Windows)
# or target/release/cortexa-mcp (macOS / Linux)

The bridge reads its config from the CLI config file, so configure it once:

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

Then add it to Claude Code:

claude mcp add cortexa "C:\\path\\to\\target\\release\\cortexa-mcp.exe"

On macOS / Linux, use the appropriate path without the .exe extension.

You can also pass credentials via environment variables instead of the CLI config:

export CORTEXA_URL=http://127.0.0.1:7373
export CORTEXA_TOKEN=<TOKEN>

Environment variables override the CLI config file when set.

Verify the Connection

Inside Claude Code, type:

/mcp

You should see cortexa listed with its tools (the full list is in the MCP Tools reference). Some of them:

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

If the tools don't appear, check that Cortexa is running and the token is correct. You can test the API directly:

curl http://127.0.0.1:7373/api/health -H "Authorization: Bearer <TOKEN>"

Usage Examples

Capture a decision during a coding session

Claude Code can capture thoughts on your behalf as you work:

"Save to Cortexa: decided to use HNSW instead of brute-force for the embedding index"

The agent calls cortexa_capture with structured metadata including the project name, file context, and thought type.

Pull context at the start of a session

Ask the agent to check your vault before starting work:

"Check Cortexa for any prior decisions about the auth middleware"

The agent calls cortexa_context with your query, project name, and the files you're working with. Results come back grouped by thought type (decisions first, then architecture, patterns, debug findings, TODOs).

Zero-prompt context injection

For fully automatic context, generate a .cortexa-context.md file in your project:

cortexa-cli sync-context MyProject --dir /path/to/project

Claude Code reads project files automatically, so it will consume this context without any tool call. Add .cortexa-context.md to your .gitignore since it is machine-generated and user-specific.

Per-Integration Tokens

Instead of sharing your global token, you can issue a dedicated token for Claude Code in Settings → Tokens. Per-integration tokens are revocable and track last_used_at so you can see when each client was last active.

Troubleshooting

Tools don't appear after claude mcp add — Restart Claude Code. The MCP connection is established on startup.

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

cortexa_context returns empty results — Your vault may not have enough embedded items yet. Check that an embedding provider is configured in Settings → LLM and that items have been processed (look for the embedding job queue in Settings → Storage).

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.