Skip to content

Claude Desktop Connectors — CodeNavi Setup

How to expose CodeNavi as a Custom Connector in Claude Desktop (Settings → Connectors → Add custom connector).

This is Claude Desktop's Home / chat surface. The Code tab inside Claude Desktop is Claude Code — it reads a project .mcp.json directly over plain-HTTP localhost (no connector, no tunnel); see claude-integration.md. Use this guide only for the chat side or when you want CodeNavi reachable from another device/phone.

When to use this guide

Use this guide if you want CodeNavi to appear in Claude Desktop's Connectors UI (the toggle list next to the chat input). This is different from the local claude_desktop_config.json + mcp-remote path documented below.

Path Transport When to use
claude_desktop_config.json + mcp-remote Local bridge to http://localhost:8765/mcp Single-machine setup, no public exposure
Custom Connector (this guide) Direct HTTPS to a public URL Multi-device, mobile, or you want the connector toggle UI

Local bridge (single machine)

Claude Desktop's chat speaks stdio only, so on the machine that runs CodeNavi it needs the mcp-remote bridge (Node) — a direct http URL won't connect. In claude_desktop_config.json:

{
  "mcpServers": {
    "codenavi": {
      "command": "npx",
      "args": [
        "mcp-remote", "http://localhost:8765/mcp",
        "--header", "Authorization: Bearer YOUR_TOKEN_HERE"
      ]
    }
  }
}

Replace YOUR_TOKEN_HERE with CODENAVI_AUTH_TOKEN from your .env. Without it every call returns 401 and the tools never register. On Windows, cmd.exe mangles the space in the header value — drop the --header pair and use the Custom Connector path below instead (windows.md).

Prerequisite — an HTTPS URL

The Connectors UI requires HTTPS and a publicly reachable URL. CodeNavi binds to :8765 over plain HTTP, so you need an auth token and a tunnel in front of it — both covered in Remote access over HTTPS (Tailscale Funnel recommended, Cloudflare Tunnel as the alternative). Do that first and come back with your https://… URL and token.

Add the connector in Claude Desktop

  1. Open Claude Desktop → Settings → Connectors
  2. Click Add custom connector
  3. Fill in:
  4. Name: CodeNavi
  5. Remote MCP server URL: https://<your-url>/mcp (e.g. https://codenavi-host.tail1234.ts.net/mcp)
  6. Claude Desktop will prompt for authentication. Choose Custom header and add:
  7. Header name: Authorization
  8. Header value: Bearer <your-token>
  9. Save. The connector should show as Connected and CodeNavi's 11-tool core appears in the tool toggle; the relations, wiki, notes and crawler tools load on demand via reveal_tools.

Test it

In a new chat, toggle the CodeNavi connector on and ask:

Use semantic_search to find where authentication is handled.

Claude should call the tool over HTTPS through the tunnel.

Multi-codebase scoping

If your CodeNavi instance hosts multiple codebases, point the connector at a scoped endpoint:

https://<your-url>/mcp/myproject

Each codebase needs its own connector entry in Claude Desktop. See remote-access.md for the endpoint table and setup.md for how scoped endpoints work.

Troubleshooting

Tunnel-side problems (can't connect, 401, timeouts, reconnect notices) are covered in Remote access → Troubleshooting. Desktop-specific notes:

Connector shows "Failed to connect"

Work through the tunnel checks first (remote-access.md); if the URL curls fine from another machine but Claude Desktop still refuses, re-add the connector — a stale entry can cache a dead URL.

"401 Unauthorized" in Claude Desktop

The token in the connector's Authorization header doesn't match CODENAVI_AUTH_TOKEN in deploy/.env. Re-paste it carefully — no extra whitespace, include the Bearer prefix.

Connector keeps "reconnecting" between calls

Cosmetic — CodeNavi runs stateless_http=True, and some clients show SSE reconnect notices after each tool call. Tool results still return correctly.