Set Up Canopy with Claude Code

Claude Code speaks MCP natively. Canopy runs as a local MCP server over stdin/stdout — no daemon, no cloud dependency — and exposes one tool: canopy_answer. Claude Code routes any code-intelligence question through it: locate a symbol, trace dependents, explain a file, get an architecture overview.

Fastest path: `canopy setup`

Run canopy setup inside the repo. The editor-wiring step detects Claude Code and writes the MCP config for you; the same command also handles licensing, the embedding runtime, and the initial index. Most users never hand-edit MCP config.

cd /path/to/your/repo
canopy setup          # interactive; accept the defaults
canopy setup --yes    # zero prompts

Already onboarded and only need the editor wiring? Re-run just that step:

canopy setup --only mcp

If canopy setup wired Claude Code for you, skip ahead to Verify the connection.

Create .mcp.json at the repo root:

{
  "mcpServers": {
    "canopy": {
      "command": "canopy",
      "args": ["serve"]
    }
  }
}

canopy serve defaults to the current directory, which is the project root when Claude Code spawns the server. This is the recommended setup: one .mcp.json per repo, committed alongside the code. Add "--watch" to args to re-index changed files automatically during a session.

To make one repo’s Canopy server available in every Claude Code session, add it to ~/.claude/.mcp.json with an explicit path:

{
  "mcpServers": {
    "canopy-platform": {
      "command": "canopy",
      "args": ["serve", "/absolute/path/to/your/repo"]
    }
  }
}

You can mix scopes: a per-repo entry named canopy-thisrepo plus a user-global canopy-platform both connect.

Canopy prints its own wiring snippet, including a claude mcp add one-liner, so you never have to type the JSON by hand:

canopy serve --print-mcp-config

Verify the connection

Restart Claude Code — MCP configs load at session start. Then run:

/mcp

You should see canopy listed as connected, exposing one tool: canopy_answer. Test it with a real question:

where is the function createPayment defined?

Claude Code calls canopy_answer and returns the definition site from the index. If the server doesn’t appear, check its stderr under /mcp logs.

Common pitfalls

canopy command not found Claude Code spawns the server in a fresh shell that may not inherit your $PATH. Use the absolute path:

"command": "/usr/local/bin/canopy"

Run which canopy in your terminal to find it.

“Index not found” The MCP server expects an index for the repo. Run canopy index . once in the repo root (or run canopy setup, which indexes for you), then restart Claude Code.

Server connects but answers look wrong or stale Run canopy doctor — it reports install info, index status, and the active backend. If the index is stale, canopy index . updates it incrementally; canopy index --full rebuilds from scratch.

Compliance shells

For a “nothing leaves the box” session, index with --no-network and pass the same flag through the MCP config:

{
  "mcpServers": {
    "canopy": {
      "command": "canopy",
      "args": ["--no-network", "serve"]
    }
  }
}

Canopy refuses any cloud-backend configuration under this flag and exits with code 2 on violation.