Connecting CodeNavi to VS Code¶

VS Code now has native MCP support (built into agent mode, GA since mid-2026), and several AI agent extensions add their own. They all talk to CodeNavi over the same Streamable-HTTP endpoint — what changes is where the config goes and the exact key shape, which differs more than people expect. There is no CodeNavi-specific VS Code extension yet (see Native extension status); pick a path below and you get the full 33-tool surface (41 with the crawler). By default the server advertises an 11-tool core — search/browse/read plus reindex_incremental, reindex_status, index_stats — and loads the rest on demand: reveal_tools() lists the hidden groups, reveal_tools(call="<tool>", args='{…}') reveals and runs one in a single step.

The universal endpoint¶

URL: http://localhost:8765/mcp (unscoped) or /mcp/<codebase> (scoped) — localhost only if the client runs on the server's machine; otherwise the server's host:port (remote-access.md)
Header: Authorization: Bearer <CODENAVI_AUTH_TOKEN>
Get the token from your install's .env: grep '^CODENAVI_AUTH_TOKEN=' .env | cut -d= -f2- (run from your install directory)

What changes per client: the top-level key (servers vs mcpServers), the type string (http vs streamableHttp vs streamable-http), the field name (url vs serverUrl), and whether the token is literal vs env-var. A block copied from one client into another usually fails silently. The exact shapes:

VS Code (native MCP)¶

Built in — no extension needed. Config lives in .vscode/mcp.json (workspace) or your user mcp.json (Command Palette → MCP: Open User Configuration). The top-level key is servers (NOT mcpServers) and the type is http:

{
  "servers": {
    "codenavi": {
      "type": "http",
      "url": "http://localhost:8765/mcp",
      "headers": { "Authorization": "Bearer <PASTE_TOKEN>" }
    }
  }
}

Verify with MCP: List Servers. A literal Bearer <token> works; VS Code also supports ${input:...} secret prompting (pair it with an inputs array) if you'd rather not store the token in the file.

Air-gap note: the MCP link to CodeNavi works offline, but native agent mode against a fully-local model is newer and version-dependent (VS Code 1.122+, the "Local" agent provider, a tool-calling-capable local model); the default Copilot model needs cloud sign-in. For a guaranteed-offline VS Code setup, use Cline / Roo / Continue with a local model (below).

Cline¶

Open the Cline panel → MCP Servers → Configure, or edit cline_mcp_settings.json directly. Cline's remote type is streamableHttp (camelCase):

{
  "mcpServers": {
    "codenavi": {
      "type": "streamableHttp",
      "url": "http://localhost:8765/mcp",
      "headers": { "Authorization": "Bearer <PASTE_TOKEN>" },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Save → Cline auto-reconnects. Cline runs fully air-gapped pointed at a local model (Ollama / LM Studio / any OpenAI-compatible endpoint).

Roo Code¶

A Cline fork, but the shape differs — the type is streamable-http (hyphenated) and the auto-approve key is alwaysAllow (not autoApprove). Config is .roo/mcp.json (project) or the global mcp_settings.json:

{
  "mcpServers": {
    "codenavi": {
      "type": "streamable-http",
      "url": "http://localhost:8765/mcp",
      "headers": { "Authorization": "Bearer <PASTE_TOKEN>" },
      "alwaysAllow": []
    }
  }
}

Also fully air-gappable with a local Ollama model.

Continue¶

Continue's config is YAML, not JSON — mcpServers is a list, and headers go under requestOptions. Put it in .continue/mcpServers/codenavi.yaml (or the mcpServers block of config.yaml):

mcpServers:
  - name: codenavi
    type: streamable-http
    url: "http://localhost:8765/mcp"
    requestOptions:
      headers:
        Authorization: "Bearer <PASTE_TOKEN>"

Reload Continue and pick a tool-use-capable model. Fully air-gappable with Ollama.

Cursor¶

.cursor/mcp.json (project-scoped) or ~/.cursor/mcp.json (global). Field name is url, no type needed:

{
  "mcpServers": {
    "codenavi": {
      "url": "http://localhost:8765/mcp",
      "headers": { "Authorization": "Bearer <PASTE_TOKEN>" }
    }
  }
}

Restart Cursor (or Cmd/Ctrl-Shift-P → Cursor: Reload MCP).

If Cursor shows SSE error: Non-200 status code (404), ignore the 404. CodeNavi has no SSE endpoint; Cursor only fell back to SSE because its POST failed. The real cause is in the POST, not a wrong URL — almost always a missing/incorrect Authorization: Bearer token, or a scoped /mcp/<codebase> naming a codebase that doesn't exist (check list_codebases; a single-codebase install is usually default). Open MCP user-codenavi.log (Output → MCP) and read the first WARNING line — it carries the true error (e.g. Unauthorized); the surfaced error is the meaningless SSE 404.

Windsurf (Cognition/Devin)¶

~/.codeium/windsurf/mcp_config.json. Field name is serverUrl (same as Antigravity, opposite of Cursor):

{
  "mcpServers": {
    "codenavi": {
      "serverUrl": "http://localhost:8765/mcp",
      "headers": { "Authorization": "Bearer <PASTE_TOKEN>" }
    }
  }
}

Restart Windsurf, check Cascade's tool list. Cascade's model is cloud-hosted — your code leaves the machine.

Any other VS Code MCP client¶

The pattern is constant: an HTTP MCP block with a URL field (url or serverUrl) and a Bearer header. If a client can't send headers, run mcp-remote as a local stdio bridge. Client on another machine than the server? No bridge needed for the clients above — swap localhost:8765 for the server's address and keep the bearer token; see remote-access.md, including its warning about tunnelling onto port 8765 of a Windows box that port-proxies a WSL2 CodeNavi.

The things that bite people¶

Top-level key varies. VS Code native uses servers; everyone else uses mcpServers. A mcpServers block dropped into .vscode/mcp.json does nothing.
type string varies. http (VS Code), streamableHttp (Cline, camelCase), streamable-http (Roo, Continue, hyphen). Cursor needs no type.
Field name varies. url (VS Code, Cursor, Cline, Roo) vs serverUrl (Windsurf, Antigravity).
Token form varies. Most take a literal Bearer string (no ${VAR}); VS Code native additionally supports ${input:...} prompting.
Scoped vs unscoped /mcp. Use unscoped /mcp unless you know the codebase name; /mcp/<name> returns Unknown codebase (404) for an unconfigured name. Get the names from /health, ./codenavi codebases, or the Web UI System tab. A bare trailing slash (/mcp/) is treated as unscoped¹ — it no longer 404s on an empty codebase name.
Agents cache MCP server lists. After editing a config file, fully restart the host — reloading the window isn't always enough.

Privacy & air-gap¶

What the agent's model sees, it sends to wherever that model runs. Cursor → Anthropic/OpenAI, Windsurf → Cognition cloud, native Copilot → GitHub/OpenAI — all cloud. Cline, Roo Code, and Continue can run on a local model (Ollama / LM Studio / vLLM — CodeNavi's own on-box LLM providers), which makes the whole loop air-gappable: the localhost MCP link needs no internet and the model stays on the box. The CodeNavi server itself never phones home. (This is the split the /connect wizard shows as "local-model capable" vs "cloud-model agents".)

Native CodeNavi extension status¶

"VS Code native MCP" (above) is built into VS Code. A dedicated CodeNavi for VS Code extension (sidebar search panel, status-bar item, raw /ui/api/* calls — no AI agent in the loop) is a separate thing, on the roadmap but not shipped. Until then the agent paths above give the identical 33-tool surface (41 with the crawler). File an issue if a native panel would unlock your workflow.

Other MCP clients¶

JetBrains family, Neovim AI extensions (e.g. avante.nvim): same http://localhost:8765/mcp endpoint + bearer token; config lives wherever the extension's docs say. Zed has its own guide — docs/connecting-zed.md (it uses a context_servers block).

Vendor change reference CN-350. ↩