Connecting CodeNavi to AnythingLLM¶

How to give an AnythingLLM agent access to CodeNavi's code-search tools over MCP — so a workspace running a local code model (Codestral-22B, DeepSeek-Coder, …) retrieves from CodeNavi's code-specialist index instead of AnythingLLM's general-purpose one.

When to use this guide¶

You run AnythingLLM (Desktop or Docker) as your chat/agent front-end, and you want its agent to call CodeNavi's MCP tools — semantic_search, symbol_search, codebase_overview, read_file, and the rest (relations tools such as find_references load on demand: the agent calls reveal_tools first). AnythingLLM brings the LLM and the chat UX; CodeNavi brings code-specialist retrieval, AST-aware chunking, and secret/injection scanning. They connect natively over MCP — no bridge process required.

Choosing between the two rather than combining them? They're complementary, not competing. AnythingLLM is a general RAG workspace; CodeNavi is the retrieval layer it's missing for code. The strongest setup wires both together (see Where DeepSeek-Coder / Codestral fit).

How it works¶

AnythingLLM (Desktop or Docker)               CodeNavi (Docker, host-networked)
┌────────────────────────────────┐           ┌───────────────────────────────┐
│ Workspace LLM — the "brain"     │           │  MCP server  :8765/mcp/<cb>   │
│   Ollama / LM Studio:           │  MCP over │   Buric-E4B code embedder     │
│   Codestral-22B, DeepSeek-Coder │─streamable│   AST chunking · reranker     │
│ Agent (@agent) ── MCP client    │──HTTP────▶│   secret + injection scanner  │
└────────────────────────────────┘           └───────────────────────────────┘

Three things have to line up:

CodeNavi exposes its MCP server over Streamable HTTP at /mcp (scoped: /mcp/<codebase>).
AnythingLLM registers it in anythingllm_mcp_servers.json as a streamable server.
You drive it from Agent mode (@agent) — MCP tools are agent-only in AnythingLLM.

Privacy first¶

AnythingLLM can run fully local — and for code, that's the point. The chunks CodeNavi returns are placed into the workspace LLM's prompt on every agent turn. Where those chunks go depends entirely on which LLM the workspace uses:

Workspace LLM	Where the retrieved code goes
Local (Ollama / LM Studio: Codestral-22B, DeepSeek-Coder, …)	Stays on the box. Nothing leaves.
Cloud (OpenAI, Anthropic, Gemini, …)	Sent to that provider on every agent turn.

For proprietary code, run a local model in AnythingLLM. The DeepSeek-Coder / Codestral setup people reach for is exactly the private path — keep it that way and the whole pipeline (retrieval and generation) runs with no egress. Note that setup.sh generates an auth token by default, and a non-loopback bind with no token refuses to start — see Step 4 and the security notes before exposing it past localhost.

Prerequisites¶

CodeNavi running and reachable at http://localhost:8765/health.
CodeNavi launched with the HTTP transport — the Docker deploy does this; it serves /mcp. (A raw curl …/mcp returns nothing useful; /mcp speaks the MCP Streamable-HTTP protocol, not REST. Smoke-test with /health.)
AnythingLLM Desktop or Docker, with a workspace and a configured LLM (local recommended).
The codebase you want to expose already indexed — run list_codebases or check /health for the names.

Step 1 — Open the MCP servers config¶

Desktop: open the Agent Skills page in the AnythingLLM UI once. It creates anythingllm_mcp_servers.json if it doesn't exist and gives you an editor for it.

Docker: the file lives at plugins/anythingllm_mcp_servers.json inside the storage directory (STORAGE_LOCATION) — i.e. /app/server/storage/plugins/anythingllm_mcp_servers.json in the container, which maps to whatever host directory you mounted as the storage volume.

Step 2 — Register CodeNavi¶

{
  "mcpServers": {
    "codenavi": {
      "type": "streamable",
      "url": "http://localhost:8765/mcp/<your-codebase>",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN_HERE"
      }
    }
  }
}

YOUR_TOKEN_HERE is CODENAVI_AUTH_TOKEN from your .env — setup.sh generates one on every install. Omit the header and every call returns 401, which AnythingLLM reports only as a server that registers no tools.

type must be "streamable" — it matches CodeNavi's default --http transport. AnythingLLM assumes sse when type is omitted, and CodeNavi only speaks SSE if launched with --sse, so set streamable explicitly.
Always use the scoped /mcp/<codebase> endpoint, not bare /mcp. Scoping pins every tool call to one codebase at the transport and rejects attempts to query another (400). Bare /mcp can search every index you've configured — including any you add later.
Replace <your-codebase> with a name from list_codebases / /health.

Step 3 — If AnythingLLM runs in Docker, reach the host¶

CodeNavi is host-networked on the host machine; an AnythingLLM container on a bridge network can't see the host's localhost. Use the host gateway:

"url": "http://host.docker.internal:8765/mcp/<your-codebase>"

On Docker Desktop (Mac/Windows) host.docker.internal resolves out of the box. On Linux, add it when you start the AnythingLLM container:

extra_hosts:
  - "host.docker.internal:host-gateway"

(Or use the host's LAN IP, or run AnythingLLM with --network=host too.) Desktop AnythingLLM talks to localhost directly — no change needed.

Step 4 — Auth (required)¶

setup.sh generates CODENAVI_AUTH_TOKEN on every install, and a server bound to a non-loopback address refuses to start without one. Send it as a Bearer header:

{
  "mcpServers": {
    "codenavi": {
      "type": "streamable",
      "url": "http://localhost:8765/mcp/<your-codebase>",
      "headers": { "Authorization": "Bearer <your-token>" }
    }
  }
}

The headers block is AnythingLLM-specific and applies only to this server. Only omit it if you deliberately run CodeNavi with no token — which the server permits on a loopback bind only, and refuses on any other.

Step 5 — Use it from an agent¶

MCP tools are available in Agent mode only. In a workspace chat, start a message with @agent, then ask something that needs the code:

@agent use semantic_search to find where requests are authenticated

AnythingLLM boots the MCP server on first use (or when you open Agent Skills); subsequent calls are fast. The CodeNavi tools then appear in the Agent Skills tool list.

Where DeepSeek-Coder / Codestral fit¶

They're the workspace LLM — the brain that reads CodeNavi's results and writes the answer. CodeNavi doesn't replace them; it feeds them. Point AnythingLLM's workspace at Ollama or LM Studio running Codestral-22B or DeepSeek-Coder, connect CodeNavi as above, and the agent retrieves with a code-specialist embedder and generates with your local code model. That's the recommended shape for private code: a strong local generator paired with retrieval that was actually built for code, instead of AnythingLLM's general-purpose default embedder (all-MiniLM-L6-v2, 384-dim, prose-trained).

Operational notes¶

One heavy client at a time. CodeNavi's searches serialize on the GPU, so a second client's searches queue behind the first; don't point two busy agents — or an agent and a reindex — at one instance.
Agent-mode only. Plain (non-agent) chat won't call MCP tools.
Auto-start. AnythingLLM starts configured MCP servers when you open Agent Skills or invoke @agent. Set "anythingllm": { "autoStart": false } on a server to keep it from booting automatically.

Troubleshooting¶

Symptom	Likely cause / fix
Tools never appear in Agent Skills	`type` mismatch — set `"type": "streamable"` (not `sse`) to match CodeNavi `--http`, then reopen Agent Skills to reboot the server.
Tools listed but every call times out / connection refused	Networking. From a Docker AnythingLLM, `localhost` is the container — use `host.docker.internal` (Step 3). Confirm `curl http://localhost:8765/health` works from the AnythingLLM host first.
`Codebase scope mismatch … 400`	The agent passed a `codebase` that differs from the scoped URL. Expected — use that codebase's own `/mcp/<codebase>` URL, or leave the call's `codebase` empty.
`401 Unauthorized`	Token enabled on CodeNavi but the header is missing/wrong. Add the `Authorization: Bearer` header (Step 4).
Calls work but answers are weak	The workspace LLM is the limit, not retrieval — try a stronger local code model. CodeNavi's chunks are only as useful as the model reading them.

Security & privacy notes¶

LLM choice = egress. Local model → nothing leaves; cloud model → retrieved code is sent to that provider every turn. Choose accordingly for proprietary code.
Scope, don't trust. Use /mcp/<codebase>, never bare /mcp. The scoped endpoint enforces the boundary at the transport; the unscoped one does not.
Authenticated by default; a tokenless network bind refuses to start. setup.sh generates CODENAVI_AUTH_TOKEN for you, and the server will not start on a non-loopback bind without one (CODENAVI_ALLOW_NO_AUTH=1 acknowledges the risk if you really want that on a trusted single-user host). A loopback-only bind with no token is fine. Add TLS before exposing it on a network.
Metadata still visible. list_codebases / /health reveal all configured codebase names and paths regardless of scope. Run a single-codebase instance if even those are sensitive.