Set Up Canopy with Claude Code

Claude Code supports MCP servers out of the box. Canopy runs as a local MCP server over stdin/stdout — no daemon, no cloud dependency. Once configured, all 21 Canopy tools appear in Claude Code’s tool list and Canopy injects its own behavioral instructions at the start of every session.

Prerequisites

Canopy installed and on your PATH (canopy --version returns a version string)
At least one repo indexed (canopy index /path/to/repo)
Claude Code installed

If you haven’t installed Canopy yet, see Install Canopy.

Add Canopy to `.mcp.json`

Create .mcp.json in the root of the repo you want to analyze:

{
  "mcpServers": {
    "canopy": {
      "command": "canopy",
      "args": ["serve", ".", "--watch"],
      "env": {}
    }
  }
}

Claude Code resolves . relative to where .mcp.json lives — the project root. This is the recommended setup: one .mcp.json per repo, committed alongside the code.

To make Canopy available in every Claude Code session regardless of project, add it to ~/.claude/.mcp.json:

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

Use an absolute path here. User-global config loads before Claude Code knows which project it’s in, so . won’t resolve consistently.

{
  "mcpServers": {
    "forge-frontend": {
      "command": "canopy",
      "args": ["serve", "/home/you/repos/frontend", "--watch"],
      "env": {}
    },
    "forge-backend": {
      "command": "canopy",
      "args": ["serve", "/home/you/repos/backend", "--watch"],
      "env": {}
    }
  }
}

Each canopy serve process is independent. Tools from both servers appear in Claude Code’s tool list.

Restart Claude Code

After editing .mcp.json, restart Claude Code. MCP server configs load at session start — a running session won’t pick up changes.

Verify the connection

In a new Claude Code session, ask:

What tools do you have from canopy?

Expected response (abbreviated):

From the canopy MCP server, I have 21 tools:

Workflow tools:
- canopy_prepare: Pre-modification analysis — dependents, health, git activity, GO/CAUTION/STOP
- canopy_validate: Post-modification check — verify changes didn't break anything
- canopy_understand: Deep comprehension of a file or symbol

Search tools:
- canopy_search: Full-text keyword search
- canopy_pattern_search: AST structural pattern search (ast-grep syntax)
- canopy_search_symbols: Symbol name search

Graph tools:
- canopy_trace_imports: Outbound imports from a file
- canopy_trace_dependents: Inbound dependents of a file
- canopy_check_wiring: Is this module reachable from an entry point?
- canopy_find_cycles: Detect circular dependency chains
- canopy_dependency_graph: Full dependency graph for a path

... (and 10 more)

If you see this, Canopy is connected and ready.

How Canopy changes Claude’s behavior

When Claude Code connects to Canopy, Canopy injects behavioral instructions into the session’s system prompt. These instructions teach Claude Code to:

Call canopy_prepare before modifying any file
Call canopy_validate after edits complete
Use canopy_understand when encountering unfamiliar code
Use graph tools (canopy_trace_dependents, canopy_trace_imports) for targeted dependency lookups

You don’t need to prompt this behavior — it’s automatic from the MCP handshake.

Common pitfalls

canopy command not found when Claude Code starts Claude Code inherits the PATH from the shell that launched it, not your interactive shell. If you installed Canopy to ~/.local/bin and your GUI launcher doesn’t source ~/.bashrc, use the absolute path in the config:

"args": ["/home/you/.local/bin/canopy", "serve", ".", "--watch"]

Wait — that should be in "command", not "args". Use:

"command": "/home/you/.local/bin/canopy"

Tools appear but return “index not found” The repo path in args doesn’t match where canopy index ran. Run canopy index . in the repo root, then restart.

Session starts but no Canopy tools appear The MCP server failed to start. Check Claude Code’s MCP logs (View → Output → MCP). The most common cause is canopy not found on PATH — see above.