Set Up Canopy with Zed

Zed supports MCP servers via its context_servers setting. Canopy connects as a local MCP server and exposes one tool, canopy_answer, in Zed’s assistant. The config lives in ~/.config/zed/settings.json (Linux/macOS) or %APPDATA%\Zed\settings.json (Windows).

Fastest path: `canopy setup`

Run canopy setup inside the repo. The editor-wiring step detects Zed and writes the context_servers entry 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 Zed for you, skip ahead to Verify the connection.

Add a context_servers block to your Zed settings:

{
  "context_servers": {
    "canopy": {
      "command": {
        "path": "canopy",
        "args": ["serve"]
      },
      "settings": {}
    }
  }
}

Save. Zed reconnects within a few seconds.

For a per-project server (typically when you work across multiple repos), add a project-local override at <repo>/.zed/settings.json:

{
  "context_servers": {
    "canopy-thisrepo": {
      "command": {
        "path": "canopy",
        "args": ["serve"]
      },
      "settings": {}
    }
  }
}

Zed merges project-local context servers with user-global ones, so name the project-scoped entry distinctly (e.g. canopy-thisrepo vs canopy-platform) to avoid overlap.

Canopy prints the exact block for you:

canopy serve --print-mcp-config --client zed

Verify the connection

Open the assistant panel and its tool inspector (the wrench icon). Canopy’s single tool, canopy_answer, should appear under the canopy namespace. Test it:

@canopy: what is the architecture of this repo?

The assistant runs canopy_answer and returns the repo’s shape summary.

Common pitfalls

Zed doesn’t pick up the new server Zed caches MCP connections. Quit and relaunch (Cmd-Q on macOS) — a soft window close isn’t sufficient.

canopy not found Zed’s MCP spawn doesn’t always inherit your shell $PATH. Use an absolute path in command.path, such as /usr/local/bin/canopy or /opt/homebrew/bin/canopy. Run which canopy in a terminal to find it.

Tools appear but calls error Run canopy doctor separately to verify the binary, index status, and active backend. If it fails in the shell, it fails in Zed too — fix the underlying issue first. For a missing index, run canopy index . in the repo root.

Compliance shells

For an audit-grade “nothing leaves the box” configuration:

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

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