Skip to content

Connecting CodeNavi to GitHub Copilot CLI

GitHub Copilot CLI (copilot, npm package @github/copilot, Node 22+) is GitHub's terminal coding agent. It speaks MCP over HTTP, installs CodeNavi's Claude Code plugin from your server, and can run on a local model with no GitHub login. Verified on Copilot CLI 1.0.97 with a local llama3.1 8B.

1. Add the server

export CODENAVI_AUTH_TOKEN=$(grep '^CODENAVI_AUTH_TOKEN=' /path/to/install/.env | cut -d= -f2-)
copilot mcp add --transport http \
  --header 'Authorization: Bearer ${CODENAVI_AUTH_TOKEN}' \
  codenavi http://localhost:8765/mcp
copilot mcp list      # User servers: codenavi (http)

That writes ~/.copilot/mcp-config.json. Copilot expands ${CODENAVI_AUTH_TOKEN} when it connects, so the file holds the placeholder, not the token. Keep the single quotes, so your shell does not expand it first. Written by hand, the same entry:

{
  "mcpServers": {
    "codenavi": {
      "type": "http",
      "url": "http://localhost:8765/mcp",
      "headers": { "Authorization": "Bearer ${CODENAVI_AUTH_TOKEN}" },
      "tools": ["*"]
    }
  }
}

If your server runs with auth off, drop the --header.

2. Optional: the plugin (skills + session hook)

Copilot CLI installs Claude Code-format plugins, and your CodeNavi server serves its plugin over git:

copilot plugin marketplace add http://localhost:8765/plugins/claude.git
copilot plugin install codenavi@codenavi     # Installed 2 skills.

This adds the using-codenavi and compliance-check skills. It also adds the SessionStart hook, which tells the model to search with CodeNavi before grep. The plugin does not connect the server: Copilot skips the plugin's MCP entry because its URL is a template for Claude Code. Step 1 is still required. The plugin's slash commands and grep hook are untested in Copilot.

Run it on a local model

Copilot CLI takes any OpenAI-compatible endpoint (BYOK). With COPILOT_OFFLINE=true it also turns off GitHub sign-in, telemetry, web tools and auto-update, so no code leaves the machine:

export COPILOT_OFFLINE=true \
       COPILOT_PROVIDER_BASE_URL=http://127.0.0.1:11434/v1 \
       COPILOT_MODEL=llama3.1:latest
copilot

Without these variables Copilot uses GitHub's hosted models, which need a Copilot subscription and /login.

Verify

copilot mcp list shows codenavi (http) but no connection status. To check the token, run one prompt:

copilot --allow-tool codenavi -p "Use the codenavi MCP tools only. Call list_codebases and tell me the codebase names."

The output shows ● list_codebases (MCP: codenavi) and then the names. To the model the tools are named codenavi-semantic_search, codenavi-read_file, and so on. --allow-tool codenavi allows that one server and nothing else.

Under the server's default lean profile, the model sees only the 11-tool core and reveal_tools. Load the rest with reveal_tools(group="relations"), or use reveal_tools(call=…) to reveal and run a tool in one step.

The things that bite people

  1. The plugin alone gives no tools. Copilot does not expand ${VAR} in an MCP URL, and it drops the plugin's entry, whose URL is a ${CODENAVI_HOST:-localhost} template. Its debug log blames the shape instead (Invalid MCP config … mcpServers: Required). Add the server with copilot mcp add.
  2. Quote the placeholder. With double quotes the shell writes the real token (or an empty string) into mcp-config.json. With the placeholder kept, export CODENAVI_AUTH_TOKEN in the shell that starts copilot, or the server answers 401.
  3. Headless needs a permission flag. copilot -p has no one to approve tool calls. Pass --allow-tool codenavi, plus whatever else the task needs (or --allow-all-tools).
  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.

Privacy

On GitHub's hosted models, your prompts and the code chunks CodeNavi returns go to GitHub. With COPILOT_OFFLINE=true and a local provider, everything stays on the machine. The CodeNavi server itself never phones home.