Cursor

Integrate Cortexa with Cursor IDE to provide your AI coding assistant with project-specific memory and context from 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
• Cursor IDE installed

Configuration

Cursor reads MCP server config from mcp.json. You can configure it at two levels:

Scope	File path
Global (all projects)	~/.cursor/mcp.json
Project-scoped	.cursor/mcp.json in your project root

Cursor supports both HTTP and stdio transports.

Option A — HTTP Transport (Recommended)

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

Create or edit your mcp.json:

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

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

Option B — stdio Transport

If you prefer the standalone stdio bridge, first build it:

cargo build -p cortexa-mcp --release

Then configure mcp.json:

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>"
      }
    }
  }
}

macOS / Linux

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

The bridge also reads credentials from the CLI config file (cortexa-cli config --url ... --token ...), so you can omit the env block if that's already set up. Environment variables take precedence when both are set.

Restart Cursor

After saving mcp.json, restart Cursor. Verify the connection in Settings → MCP where the Cortexa tools should appear.

Available Tools

Once connected, Cursor's AI assistant 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

Pull context while coding

In Cursor's chat, ask:

Check Cortexa for any decisions about how we handle authentication

The assistant calls cortexa_context with your query and returns relevant prior thoughts grouped by type.

Capture decisions as you code

Save to Cortexa: switched from JWT to session cookies for the admin panel because of XSS risks

The assistant calls cortexa_capture with the thought type, project name, and relevant file paths.

Zero-prompt context injection

Generate a context file that Cursor reads automatically:

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

This creates .cortexa-context.md in your project root. Cursor scans project files, so your agent gets your institutional memory without any tool call. Add .cortexa-context.md to your .gitignore.

Project-Scoped vs Global

• Use ~/.cursor/mcp.json if you want Cortexa available in every Cursor project.
• Use .cursor/mcp.json in a specific project root to limit it to that project. Add this file to .gitignore if it contains your token.

Troubleshooting

Tools not showing in Settings → MCP — Make sure the JSON is valid (no trailing commas). Restart Cursor after editing mcp.json.

"Connection refused" errors — Verify the Cortexa desktop app is running. The HTTP API is localhost-only on port 7373 by default.

423 Locked responses — The vault is locked via idle lock. Unlock the Cortexa app first.

Using both global and project configs — Cursor merges them. If both define a cortexa server, the project-scoped one takes precedence.

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.