Set Up Canopy with Cursor

Cursor supports MCP servers. Canopy connects as a local MCP server and exposes one tool, canopy_answer, which Cursor’s AI can call for any code-intelligence question: 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 Cursor 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

To re-run only the editor wiring on an already-onboarded machine: canopy setup --only mcp.

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

Open Cursor → Settings → AI → MCP Servers → Add Server.
Enter:
- Name: canopy
- Command: canopy
- Args: serve
Save. Cursor restarts the MCP connection.

The settings panel shows a green dot next to canopy when connected. Hovering reveals the tool list — a single entry, canopy_answer.

Cursor also reads ~/.cursor/mcp.json:

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

This config is per-user; Cursor does not support per-repo MCP overrides. To pin the server to one repo regardless of what Cursor has open, pass the path explicitly: "args": ["serve", "/absolute/path/to/your/repo"].

Canopy prints the exact block for you:

canopy serve --print-mcp-config --client cursor

Verify the connection

Restart Cursor, then open the chat panel, click the tool icon (@ or +), and search for canopy. The single canopy_answer tool should appear.

Test it with a real question:

use canopy to find where the auth flow lives and what calls it

Cursor should call canopy_answer rather than its built-in grep.

Common pitfalls

Tools don’t appear after adding the server Cursor caches the MCP server list across launches. Quit Cursor fully (not just close the window — full quit on macOS), then reopen.

canopy command not found Cursor’s MCP spawn shell may not inherit your $PATH. Use an absolute path such as /usr/local/bin/canopy or /opt/homebrew/bin/canopy in the Command field. Run which canopy in a terminal to find it.

Cursor calls grep instead of canopy_answer Cursor weights its built-in tools ahead of MCP tools by default. Add a line to your Cursor system prompt (Settings → AI → System Prompt) to bias the agent:

For codebase questions, prefer canopy_answer over grep/read.

“Index not found” Run canopy index . in the repo root (or canopy setup, which indexes for you), then restart Cursor.

Compliance shells

For a “nothing leaves the box” configuration:

{
  "mcpServers": {
    "canopy": {
      "command": "/usr/local/bin/canopy",
      "args": ["--no-network", "serve"]
    }
  }
}

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