Skip to content

Connecting CodeNavi to Zed

Zed speaks MCP natively. Its Agent Panel calls MCP servers as "context servers", configured under a context_servers key in Zed's settings.json. Point one at CodeNavi and you get CodeNavi's tools inside Zed's agent — an 11-tool search/browse/read core by default, with find_callers, impact_analysis and the rest a reveal_tools() call away (config.md).

context_servers, not mcpServers. This is the one thing that trips up people copying a config from Cursor/Cline. Zed's top-level key is context_servers. The per-server fields (url, headers) are the same.

The endpoint

  • URL: http://localhost:8765/mcp (unscoped) or /mcp/<codebase> (scoped)
  • 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)

Configure it

Open the settings file with zed: open settings from the command palette (Cmd/Ctrl-Shift-P), or edit ~/.config/zed/settings.json directly. For a single project you can use .zed/settings.json in the repo root instead. Add:

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

If your server runs with auth turned off, drop the headers line — just the url is enough.

You can also add it from the UI: Agent Panel → ⚙ / + → Add Custom Server (the agent: add context server action). Either way Zed writes the same context_servers block.

Verify

Open the Agent Panel. codenavi should show as connected with its tools listed. If it doesn't appear, re-run agent: add context server or restart Zed — the agent caches its server list between sessions. Then try:

"Use semantic_search to find where payment processing happens."

The things that bite people

  1. Top-level key is context_servers, not mcpServers. A block copied from a Cursor/Cline config silently does nothing in Zed.
  2. Paste the literal token. Zed does not expand ${VAR} inside settings.json. Put the real Bearer value in the header and keep the file private (chmod 600 ~/.config/zed/settings.json if it's the user-global one).
  3. No Authorization header = OAuth prompt. When a remote context server has no configured auth header, Zed kicks off the standard MCP OAuth flow. CodeNavi uses a static bearer token, not OAuth — so when auth is on, always include the header. (With auth off, CodeNavi never challenges, so plain url is fine.)
  4. Unscoped vs scoped /mcp. Use unscoped /mcp unless you know the codebase name. /mcp/<name> returns Unknown codebase (404) for any <name> that isn't configured; a single-codebase install is usually named default. Check with list_codebases.

A note on the Zed extension API

Zed also has an MCP-server extension API (extension.toml → [context_servers.…] → a context_server_command). That path is for shipping a server as a packaged binary/NPM command — it does not apply here. CodeNavi is a remote HTTP server, so the context_servers settings block above is the right (and simpler) way in. Zed is also phasing out MCP-server extensions in favour of the official MCP registry, so prefer the settings block regardless.

Privacy

Zed's Agent Panel sends your prompts — and therefore the code chunks CodeNavi returns — to whichever model you've configured (Anthropic, OpenAI, or a local Ollama/LM Studio endpoint). Whatever leaves the agent leaves your machine. Scope CodeNavi to codebases you're comfortable sharing, or point Zed at a local model for fully on-box search + chat. The CodeNavi server itself never phones home.