Gemini CLI

Set up Cortexa with Gemini CLI to augment Google's AI assistant with your personal knowledge base and thought history.

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
• Gemini CLI installed
• The cortexa-mcp stdio bridge binary (Gemini CLI uses stdio MCP)

Build the stdio Bridge

Gemini CLI uses stdio MCP with a Claude-Desktop-style config format. Build the standalone bridge:

cargo build -p cortexa-mcp --release

The binary lands at:

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

Configure Gemini CLI

Edit ~/.gemini/settings.json (create the file and directory if they don't exist).

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

Replace the path and <TOKEN> with your actual values.

Using the CLI config instead of env vars

If you have already configured the CLI:

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

The bridge reads credentials from the CLI config file automatically. Environment variables take precedence when both are set.

Verify the Connection

Launch Gemini CLI:

gemini

Inside the session, run:

/mcp list

The cortexa_* tools should appear.

Available Tools

Once connected, Gemini CLI 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
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
cortexa_brief	Retrieve the structured brief
cortexa_health	Confirm the app is reachable
cortexa_sync_context	Generate .cortexa-context.md for zero-prompt context injection

Adding to an Existing Config

If your settings.json already has other MCP servers or Gemini settings, add the cortexa key inside the existing mcpServers object:

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

Troubleshooting

/mcp list shows nothing — Make sure the JSON is valid (no trailing commas) and the binary path is correct. Restart Gemini CLI after editing the config.

"Connection refused" — Verify the Cortexa desktop app is running. The HTTP API starts automatically on app launch.

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

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.