MCP Setup

Connect any Model Context Protocol client — Claude Code, Claude Desktop, Cursor, and others — to your Cortexa vault so an AI agent can capture thoughts, search your memory, and pull institutional context as it works.

Cortexa exposes the same tools (reference) over two transports:

• HTTP (recommended) — the app serves MCP in-process at POST /mcp. Nothing to build or install; just point your client at the URL with a token.
• stdio bridge — the standalone cortexa-mcp binary, configured per client. Use it for clients that only speak stdio MCP.

Both forward to the Cortexa desktop app's local HTTP API, so the app must be running and the vault unlocked.

Prerequisites

• The Cortexa desktop app is running with the vault unlocked.
• The local API listens on http://127.0.0.1:7373 by default (bound to localhost only; change the port in Settings → API if needed).
• You have an API token (next step). All MCP/API requests are bearer-authenticated.

1. Create an API token

In Cortexa, open Settings → Tokens, create a token, and copy it. Treat it like a password — it grants full access to your vault's API, and it's stored in plaintext in your MCP client's config. Revoke or rotate it any time from the same panel.

2. Connect over HTTP (recommended)

No binary to build — point your client at the app's in-process endpoint:

• Endpoint: http://127.0.0.1:7373/mcp
• Header: Authorization: Bearer <your-token>

Claude Code

Convenience form:

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

Or the JSON config (user-global ~/.claude.json, or a project .mcp.json):

{
  "mcpServers": {
    "cortexa": {
      "type": "http",
      "url": "http://127.0.0.1:7373/mcp",
      "headers": { "Authorization": "Bearer <your-token>" }
    }
  }
}

Configured at user scope, the cortexa_* tools are available in every project you open — as long as the app is running.

Cursor

Add the same block to ~/.cursor/mcp.json (or a project's .cursor/mcp.json):

{
  "mcpServers": {
    "cortexa": {
      "url": "http://127.0.0.1:7373/mcp",
      "headers": { "Authorization": "Bearer <your-token>" }
    }
  }
}

Claude Desktop

If your Claude Desktop build supports HTTP MCP servers, use the same type: "http" block in claude_desktop_config.json (Settings → Developer → Edit Config). Older builds that only support stdio should use the bridge instead.

3. Verify

Restart your MCP client so it picks up the new server, then call cortexa_health → it should return:

Cortexa v0.14.3 up.

In Claude Code you can also run claude mcp list, which shows the connection state:

cortexa: http://127.0.0.1:7373/mcp (HTTP) - ✓ Connected

Then try cortexa_context with a description of your current work — it returns a curated brief of relevant prior thoughts.

Alternative: stdio bridge

For clients that only speak stdio MCP, use the standalone cortexa-mcp binary. It speaks JSON-RPC over stdio and forwards tools/list and tools/call verbatim to the app's POST /mcp endpoint, so it always exposes exactly the tools the HTTP transport does for the same token, and the same primary-token-only checks apply. A few things it does on its own:

• It answers initialize locally, so the client can start it before the app.
• If the app isn't running, tools/list returns the last list it fetched for this URL + token (cached in the CLI data dir); with no cached list, it returns a clear "Cortexa app isn't reachable" error.
• cortexa_capture calls made while the app is down are buffered locally (pending-captures.jsonl) and replayed on the bridge's next start or the next successful capture. Other tool calls fail with the "isn't reachable" error.

1. Build it from the repo root:

cargo build --release -p cortexa-mcp

Binary location:

• macOS / Linux: target/release/cortexa-mcp
• Windows: target\release\cortexa-mcp.exe

2. Configure its URL + token. The bridge resolves them from, in order:

1. Environment variables CORTEXA_URL and CORTEXA_TOKEN (set in the client config — recommended).
2. A cli.json in the Cortexa CLI config dir, writable with cortexa-cli config --url http://127.0.0.1:7373 --token <your-token>.

3. Register it. Claude Code:

claude mcp add cortexa \
  --env CORTEXA_URL=http://127.0.0.1:7373 \
  --env CORTEXA_TOKEN=<your-token> \
  -- /absolute/path/to/target/release/cortexa-mcp

Or JSON:

{
  "mcpServers": {
    "cortexa": {
      "command": "/absolute/path/to/target/release/cortexa-mcp",
      "env": {
        "CORTEXA_URL": "http://127.0.0.1:7373",
        "CORTEXA_TOKEN": "<your-token>"
      }
    }
  }
}

On Windows, use the .exe path and escape backslashes in JSON: "C:\\path\\to\\target\\release\\cortexa-mcp.exe".

Recommended: zero-prompt context

Once connected, run cortexa_sync_context with your project name and directory to generate a .cortexa-context.md file. Claude Code, Cursor, and other agents read this automatically at session start — giving them your institutional memory with no manual tool call. Add .cortexa-context.md to your .gitignore.

Troubleshooting

Symptom	Likely cause / fix
Unable to connect / connection refused	The Cortexa app isn't running, the vault is locked, or the port differs from 7373 (check Settings → API).
401 Unauthorized	Bad/revoked token — recreate it in Settings → Tokens and update the Authorization header (HTTP) or CORTEXA_TOKEN (bridge).
Tools don't appear in the client	The client wasn't restarted after editing config; for HTTP, confirm type: "http"; for the bridge, the command path is wrong (use an absolute path; on Windows include .exe).
Cortexa URL not configured (bridge only)	Neither CORTEXA_URL/CORTEXA_TOKEN env vars nor cortexa-cli config are set.
Cortexa app isn't reachable at … (bridge only)	The desktop app isn't running (or listens on another port). Start it and retry; restart the client if it listed no tools at startup.
this tool requires the primary API token	The tool is primary-token-only (e.g. cortexa_run_tool, foundry_run); integration tokens from Settings → Tokens don't list or call it.

Next steps

• MCP Tools reference — every tool with parameters and examples.
• Context Injection — how ambient memory works.
• Iteration Engine — agents that improve a codebase using Cortexa as memory.