Skip to content

Connecting CodeNavi to Pi

Pi is a minimal terminal coding harness, kept small at the core and extended through TypeScript extensions, skills, and packages. MCP is one of those extensions: Pi has no built-in MCP client, so you connect it to CodeNavi through the pi-mcp-adapter package. Once installed, CodeNavi's search/browse/read core shows up as Pi tools; the relations tools (find_callers, impact_analysis, diff_impact) load via reveal_tools(group="relations") — see directTools below.

Two steps, in order. Install the adapter package first, then add the server config. Skipping the install means the config is never read.

1. Install the adapter

pi install npm:pi-mcp-adapter

Restart Pi after installing so the extension loads.

2. Add the server config

The adapter looks for mcp.json in these locations; a more specific file overrides a broader one, so a project file wins over a global one:

  • ~/.config/mcp/mcp.json — user-global, shared with other MCP tools (lowest precedence)
  • ~/.pi/agent/mcp.json — Pi user-global override
  • .mcp.json — project-local, shared
  • .pi/mcp.json — Pi project override (highest precedence)

Use the standard mcpServers shape:

{
  "mcpServers": {
    "codenavi": {
      "url": "http://localhost:8765/mcp",
      "headers": { "Authorization": "Bearer ${CODENAVI_AUTH_TOKEN}" },
      "directTools": [
        "reveal_tools", "semantic_search", "file_search", "symbol_search", "grep_search",
        "find_references", "find_callers", "impact_analysis", "diff_impact",
        "graph_neighborhood", "codebase_overview", "read_file", "list_directory",
        "list_codebases", "wiki_pages", "wiki_page", "doc_sources", "index_stats",
        "search_analytics", "submit_feedback", "feedback_stats", "generate_claude_md",
        "reindex", "reindex_incremental", "reindex_full", "reindex_docs",
        "reindex_status", "cancel_reindex",
        "save_note", "search_notes", "list_notes", "delete_note"
      ]
    }
  }
}

directTools is not optional here: without it the tools stay behind the adapter's mcp() gateway and smaller local models never reach them. The list above is the full tool set minus backup/restore. Under the server's default lean profile only the 11-tool core plus reveal_tools is advertised at connect time; the rest of the list takes effect once revealed (reveal_tools(group="relations"), or reveal_tools(call=…) to reveal and run in one step). Want Pi to see every tool from the start? Set CODENAVI_TOOL_PROFILE=full on the server (config.md).

The adapter expands ${VAR} (and $env:VAR) inside headers, so you can keep the token in your environment instead of inlining it:

export CODENAVI_AUTH_TOKEN=$(grep '^CODENAVI_AUTH_TOKEN=' /path/to/install/.env | cut -d= -f2-)

Prefer not to use env interpolation? The adapter also accepts a dedicated bearer field — either a literal value or the name of an env var to read:

{
  "mcpServers": {
    "codenavi": {
      "url": "http://localhost:8765/mcp",
      "bearerTokenEnv": "CODENAVI_AUTH_TOKEN"
    }
  }
}

If your server runs with auth off, drop the header/bearer field — just url.

Verify

Restart Pi. CodeNavi's tools should appear in Pi's tool list. Then try:

"Use semantic_search to find where payment processing happens."

The things that bite people

  1. Pi has no native MCP — the adapter is mandatory. Without pi install npm:pi-mcp-adapter (then a restart), no mcp.json is read.
  2. It's mcpServers, not Pi's own settings. MCP config lives in mcp.json (the locations above), not in Pi's settings.json.
  3. Get the token interpolation right. Either use ${CODENAVI_AUTH_TOKEN} in the header and export the var, or use bearerTokenEnv/bearerToken. A literal ${...} with no exported var sends the placeholder text and the server rejects it.
  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.

The adapter's other knobs (lifecycle, idleTimeout, debug) are tuning only — see the pi-mcp-adapter package page for the full reference. directTools is the one that matters; keep it.

Privacy

Pi talks to whichever model provider you've configured. Your prompts — and the code chunks CodeNavi returns — go to that provider. Point Pi at a local provider (e.g. Ollama) for fully on-box search + chat, or scope CodeNavi to codebases you're comfortable sharing. The CodeNavi server itself never phones home.