MCP Persistent - Codanna

Codanna is a local code intelligence MCP server and CLI for AI coding agents. Persistent server mode runs continuously over stdio transport for AI assistants — Claude Code, Cursor, Codex, OpenCode, Goose, Gemini CLI.

Usage

codanna serve --watch

The server runs continuously, communicating via stdin/stdout. Use --watch to auto-reload when the index changes.

The AI client spawns this server automatically based on your config. Do not start a separate codanna serve --watch process—this causes index lock conflicts.

Config Path

The --config .codanna/settings.toml argument uses a relative path. This works when:

Project-scoped configs (Claude Code, Cursor, OpenCode, Gemini CLI): The client sets the working directory to your project root
Global configs (Claude Desktop, Goose): You must run the client from your project directory, or use an absolute path

Run one persistent server per project. Multiple servers with --watch on the same .codanna/ directory will conflict when re-indexing.

Claude Code

Add to .mcp.json in your project root:

{
  "mcpServers": {
    "codanna": {
      "command": "codanna",
      "args": ["--config", ".codanna/settings.toml", "serve", "--watch"]
    }
  }
}

This file is project-scoped and can be checked into version control.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "codanna": {
      "command": "codanna",
      "args": ["--config", ".codanna/settings.toml", "serve", "--watch"]
    }
  }
}

Claude Desktop launches from a system path, not your project directory. The relative config path .codanna/settings.toml may not resolve correctly. Use an absolute path or launch Claude Desktop from your project directory via terminal.

Cursor

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "codanna": {
      "command": "codanna",
      "args": ["--config", ".codanna/settings.toml", "serve", "--watch"]
    }
  }
}

Cursor sets the working directory to the workspace root, so relative paths resolve correctly.

Codex CLI

Add to ~/.codex/config.toml:

[mcp_servers.codanna]
command = "codanna"
args = ["--config", ".codanna/settings.toml", "serve", "--watch"]

Use mcp_servers (snake_case), not mcpServers. The camelCase key is silently ignored.

OpenCode

Add to opencode.json in your project root:

{
  "mcp": {
    "codanna": {
      "type": "local",
      "command": ["codanna", "--config", ".codanna/settings.toml", "serve", "--watch"],
      "enabled": true
    }
  }
}

OpenCode combines command and arguments into a single array under command.

Goose

Via CLI:

goose configure
# Select: Add Extension > Command-line Extension
# Name: codanna
# Command: codanna --config .codanna/settings.toml serve --watch

Or add to ~/.config/goose/config.yaml:

extensions:
  codanna:
    name: codanna
    cmd: codanna
    args:
      - "--config"
      - ".codanna/settings.toml"
      - "serve"
      - "--watch"
    type: stdio
    enabled: true

Gemini CLI

Via CLI:

gemini mcp add codanna codanna -- --config .codanna/settings.toml serve --watch

Or add to your settings.json:

{
  "mcpServers": {
    "codanna": {
      "command": "codanna",
      "args": ["--config", ".codanna/settings.toml", "serve", "--watch"]
    }
  }
}

Options

Flag	Description
`--watch`	Enable auto-reload with 500ms debounce
`--watch-interval <seconds>`	Check interval for index changes (default: 5)

Self-Test

Verify Codanna can spawn a server, access the index, and register tools:

codanna mcp-test

This tests Codanna’s MCP capabilities, not the client configurations above.

When to Use

Use Case	Recommendation
Single AI assistant	MCP Persistent (stdio)
Multiple clients	MCP Network
One-off queries	MCP Quick

​Usage

​Config Path

​Claude Code

​Claude Desktop

​Cursor

​Codex CLI

​OpenCode

​Goose

​Gemini CLI

​Options

​Self-Test

​When to Use

Usage

Config Path

Claude Code

Claude Desktop

Cursor

Codex CLI

OpenCode

Goose

Gemini CLI

Options

Self-Test

When to Use