Set Up Canopy with Cursor

Cursor supports MCP servers in its AI features. Canopy connects as a local MCP server, giving Cursor’s AI access to the same 21 code intelligence tools available in Claude Code. The config format is nearly identical — only the file location differs.

Prerequisites

Canopy installed and on your PATH (canopy --version returns a version string)
At least one repo indexed (canopy index /path/to/repo)
Cursor installed (version 0.40 or later — MCP support was added in 0.40)

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

Add Canopy to `.cursor/mcp.json`

Cursor looks for MCP server configuration in .cursor/mcp.json in the project root.

Project-local
User-global

Create .cursor/mcp.json in your project root:

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

Cursor resolves . relative to the project root where .cursor/mcp.json lives. Commit this file alongside your code so every developer on the team gets Canopy automatically.

Cursor also supports a user-level MCP config at ~/.cursor/mcp.json:

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

Use an absolute path for user-global config. This makes Canopy available in every Cursor project, always pointing at the same repo. For per-project configuration, prefer the project-local approach above.

Restart Cursor

After creating or editing .cursor/mcp.json, reload the Cursor window (Ctrl+Shift+P → “Developer: Reload Window” or restart Cursor). MCP server configs are loaded at startup.

Verify the connection

Open Cursor’s AI chat and ask:

What MCP tools do you have access to?

Expected response includes:

I have access to Canopy MCP tools, including:
- canopy_prepare
- canopy_validate
- canopy_understand
- canopy_search
- canopy_pattern_search
- canopy_search_symbols
- canopy_trace_imports
- canopy_trace_dependents
- canopy_check_wiring
- canopy_find_cycles
- canopy_dependency_graph
... (21 tools total)

Then test with a real question:

Use canopy_trace_dependents on src/index.ts and tell me what depends on it.

If Canopy is connected, Cursor’s AI calls the tool and returns a structured list of files that import src/index.ts.

Enable MCP in Cursor settings

Some Cursor versions require explicitly enabling MCP in settings. If tools don’t appear after reloading:

Open Cursor Settings (Ctrl+,)
Search for “MCP”
Enable “Model Context Protocol (MCP) servers”
Reload the window

Common pitfalls

.cursor/mcp.json not found Cursor only looks for this file in the workspace root. If you opened a sub-folder as the workspace root rather than the repo root, create .cursor/mcp.json in the folder you opened.

MCP tools visible but Canopy returns errors Run canopy index . in the repo root to ensure an index exists for the path you passed to canopy serve. If you used an absolute path in the config, verify the index was built for that same path.

Cursor’s AI doesn’t call Canopy tools automatically Unlike Claude Code, Cursor doesn’t receive Canopy’s behavioral system prompt injection in all configurations. You may need to explicitly ask Cursor to use Canopy tools: “Use canopy_prepare on this file before we edit it.”

PATH issues on macOS If Cursor was launched from the dock (not a terminal), it may not inherit your shell’s PATH. Use the absolute path to the canopy binary in the config:

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

Run which canopy in your terminal to find the absolute path.