Connect to Claude Code

Canopy speaks the Model Context Protocol (MCP) over stdin/stdout. Any MCP-compatible AI agent can connect to it. This guide covers Claude Code — the most common setup.

Add Canopy to `.mcp.json`

Claude Code looks for MCP servers in .mcp.json in your project root (project-local) or in ~/.claude/.mcp.json (user-global, applies to all projects).

Create .mcp.json in the root of the repo you indexed:

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

This config serves the current directory (.). Claude Code resolves . relative to the project root where .mcp.json lives.

If you want Canopy available in every Claude Code session, add it to ~/.claude/.mcp.json:

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

Use the absolute path to the repo when setting up user-global config — . won’t resolve consistently from different working directories.

Add --watch to have Canopy auto-update the index when files change. Useful during active development:

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

--watch adds a small background process. Skip it for large repos (100K+ files) where the file watcher overhead may be noticeable.

Restart Claude Code

After editing .mcp.json, restart Claude Code for the new server config to take effect. Claude Code loads MCP server configs at session start.

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 (use these first):
- 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 — full structural analysis 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 Claude Code doesn’t list Canopy tools, see Troubleshooting: MCP server won’t start.

How Canopy sends its own instructions

When Claude Code connects, Canopy injects behavioral instructions into the session’s system prompt automatically. This teaches Claude Code:

Call canopy_prepare before modifying any file
Call canopy_validate after modifications complete
Use canopy_understand for unfamiliar code before making plans
Use search and graph tools for targeted lookups

You don’t need to prompt Claude Code to use these patterns — Canopy’s server instructions set this behavior up automatically at the MCP handshake.

Other agents

For setup with other MCP-compatible clients, see the How-To Guides:

The MCP connection pattern is the same across all clients — only the config file location differs. See Concepts: MCP Protocol for details.

Your first workflow — use canopy_prepare before asking Claude to refactor something.