Connecting CodeNavi to OpenCode

OpenCode is an open-source AI coding agent (TUI, desktop app, and IDE extension) with native MCP support. Point it at CodeNavi's HTTP endpoint and the agent gets CodeNavi's tools (semantic_search, read_file, grep_search, … with find_callers / impact_analysis a reveal_tools call away) — the semantic index OpenCode itself doesn't ship.

Top-level key is mcp, not mcpServers. OpenCode nests servers under "mcp", and HTTP servers use "type": "remote". A block copied from a Cursor/Cline config silently does nothing.

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

OpenCode reads opencode.json from the project root (safe to commit; overrides global) or ~/.config/opencode/opencode.json (user-global). JSONC is accepted, and the files merge — later sources win on conflicting keys. Add:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "codenavi": {
      "type": "remote",
      "url": "http://localhost:8765/mcp",
      "enabled": true,
      "headers": { "Authorization": "Bearer <PASTE_TOKEN>" }
    }
  }
}

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

Committing the project file? Don't commit the literal token. OpenCode expands {env:VAR} inside header values:

"headers": { "Authorization": "Bearer {env:CODENAVI_AUTH_TOKEN}" }

then export CODENAVI_AUTH_TOKEN=… in your shell before launching opencode.

Teach the agent to prefer CodeNavi

OpenCode reads rules from AGENTS.md (project root, walking up, or global ~/.config/opencode/AGENTS.md). Paste the Agent instructions block from the /connect page into it — that block is what makes the agent reach for semantic_search before grep and respect CodeNavi's one-search-at-a-time / isolation rules. Already keeping those rules in CLAUDE.md for Claude Code? OpenCode falls back to ~/.claude/CLAUDE.md automatically, so they get picked up as-is.

Verify

From the project directory run:

opencode mcp list

codenavi shows as ✓ connected with the endpoint URL. Inside the agent, the tools appear prefixed with the server name (codenavi_semantic_search, codenavi_list_codebases, …). Then try:

"Use semantic_search to find where payment processing happens."

The things that bite people

1. Top-level key is mcp, not mcpServers — and the server type is "remote", not "streamable-http". Wrong key = silent no-op.
2. No Authorization header = OAuth attempt. For a remote server with no configured header, OpenCode auto-starts the MCP OAuth flow (Dynamic Client Registration). CodeNavi uses a static bearer token, not OAuth — when auth is on, always include the header. (With auth off, CodeNavi never challenges, so plain url is fine.)
3. 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.
4. "MCP servers add to your context." OpenCode's own docs warn about context-heavy MCP servers. CodeNavi ships a lean tool profile precisely for this — the default surface is small, and you can scope the endpoint per-codebase to keep tool lists tight.

Privacy

OpenCode sends your prompts — and therefore the code chunks CodeNavi returns — to whichever model you've configured. Point it at a local provider (Ollama / LM Studio) for a fully on-box loop; OpenCode is local-model capable, and the CodeNavi server itself never phones home. Scope CodeNavi to codebases you're comfortable sharing with whatever model the agent uses.