Connect to Claude Code

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

The automatic path

If you ran canopy setup, this step is already done: the editor-wiring step detects Claude Code and writes the MCP entry for you. Restart Claude Code and skip to Verify the connection.

To re-run just the wiring step:

canopy setup --only mcp

Manual configuration

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

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 for user-global config — . won’t resolve consistently from different working directories.

Add --watch to have Canopy re-index changed files automatically. Recommended during active development:

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

Restart Claude Code

After editing .mcp.json, restart Claude Code. MCP server configs load at session start.

Verify the connection

In a new Claude Code session, ask:

What tools do you have from canopy?

Expected response: one tool — canopy_answer. That’s the design: a single routed call instead of a tool catalog. Ask a real question to see it work:

Where is the function createSession defined?

Claude Code calls canopy_answer and gets back a file:line answer from the index. If the tool doesn’t appear, see Troubleshooting: MCP server won’t start.

How Canopy guides the agent

At the MCP handshake, Canopy provides instructions that teach the agent how to phrase questions — name the entity type, put paths and symbols in backticks — so the router locks onto the right recipe. You don’t need to prompt for this; it’s automatic.

Other agents

The connection pattern is the same across clients — only the config location differs:

See Concepts: MCP Protocol for details.

Your First Questions — the question shapes that get precise answers.