> ## Documentation Index
> Fetch the complete documentation index at: https://docs.codanna.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Persistent

> stdio server transport

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

```bash theme={null}
codanna serve --watch
```

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

<Note>
  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.
</Note>

## 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

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

## Claude Code

Add to `.mcp.json` in your project root:

```json theme={null}
{
  "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):

```json theme={null}
{
  "mcpServers": {
    "codanna": {
      "command": "codanna",
      "args": ["--config", ".codanna/settings.toml", "serve", "--watch"]
    }
  }
}
```

<Warning>
  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.
</Warning>

## Cursor

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

```json theme={null}
{
  "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`:

```toml theme={null}
[mcp_servers.codanna]
command = "codanna"
args = ["--config", ".codanna/settings.toml", "serve", "--watch"]
```

<Warning>
  Use `mcp_servers` (snake\_case), not `mcpServers`. The camelCase key is silently ignored.
</Warning>

## OpenCode

Add to `opencode.json` in your project root:

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

<Note>
  OpenCode combines command and arguments into a single array under `command`.
</Note>

## Goose

Via CLI:

```bash theme={null}
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`:

```yaml theme={null}
extensions:
  codanna:
    name: codanna
    cmd: codanna
    args:
      - "--config"
      - ".codanna/settings.toml"
      - "serve"
      - "--watch"
    type: stdio
    enabled: true
```

## Gemini CLI

Via CLI:

```bash theme={null}
gemini mcp add codanna codanna -- --config .codanna/settings.toml serve --watch
```

Or add to your `settings.json`:

```json theme={null}
{
  "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:

```bash theme={null}
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](/reference/mcp-network) |
| One-off queries | [MCP Quick](/reference/mcp-quick) |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.