Client Can't Find canopy

Symptoms

• Running canopy in a terminal returns command not found: canopy or canopy: command not found.
• Your MCP client reports “spawn failed” or a similar error when trying to start the Canopy server.
• which canopy returns no output.

---

Likely Causes

Cause	Indicator
Canopy has not been installed	which canopy returns nothing
Binary is installed but not in PATH	Binary exists at a known path but canopy fails
Shell profile not sourced	Works in a new terminal but not an existing one
Wrong shell (zsh vs bash)	PATH set in .bashrc but running zsh
macOS Gatekeeper quarantine	”cannot be opened” error — see Binary Won’t Run on macOS

---

Step-by-Step Fix

Step 1: Confirm canopy is not installed

which canopy
ls ~/.local/bin/canopy 2>/dev/null || echo "not at ~/.local/bin"
ls /usr/local/bin/canopy 2>/dev/null || echo "not at /usr/local/bin"

If none of these paths have the binary, proceed to Step 2. If the binary exists but canopy still fails, skip to Step 3.

Step 2: Install canopy

Download the binary for your platform from https://canopy.ironpinelabs.com/docs/getting-started/install-forge/. Installation is a single file copy:

macOS (Apple Silicon):

curl -fsSL https://downloads.canopy.ironpinelabs.com/latest/forge-macos-aarch64 -o canopy
chmod +x canopy
sudo mv canopy /usr/local/bin/canopy

Note: The macOS Intel build (forge-macos-x86_64) was discontinued in v1.4.3 and is no longer shipped. macOS Intel machines are not supported from v1.4.3 onward.

Linux (x86_64):

curl -fsSL https://downloads.canopy.ironpinelabs.com/latest/forge-linux-x86_64 -o canopy
chmod +x canopy
sudo mv canopy /usr/local/bin/canopy

Linux (aarch64):

curl -fsSL https://downloads.canopy.ironpinelabs.com/latest/forge-linux-aarch64 -o canopy
chmod +x canopy
sudo mv canopy /usr/local/bin/canopy

Verify the SHA-256 checksum from https://downloads.canopy.ironpinelabs.com/latest/latest.json before running.

Step 3: Add the binary location to PATH

If the binary is installed but not in your PATH, add the directory containing it to your shell profile.

For ~/.local/bin/canopy (common for user-local installs):

bash (edit ~/.bashrc or ~/.bash_profile):

export PATH="$HOME/.local/bin:$PATH"

zsh (edit ~/.zshrc):

export PATH="$HOME/.local/bin:$PATH"

fish (edit ~/.config/fish/config.fish):

set -gx PATH $HOME/.local/bin $PATH

After editing, reload your shell profile:

source ~/.bashrc    # bash
source ~/.zshrc     # zsh

Or open a new terminal window.

Step 4: Verify

which canopy
canopy --version

Expected output:

/usr/local/bin/canopy
canopy 1.3.0

Step 5: Use absolute paths in .mcp.json

If your MCP client still cannot find canopy after PATH is set, use the absolute path in .mcp.json rather than relying on PATH resolution:

{
  "mcpServers": {
    "canopy": {
      "command": "/usr/local/bin/canopy",
      "args": ["serve", "/path/to/your/repo"]
    }
  }
}

Replace /usr/local/bin/canopy with the output of which canopy. GUI applications (like VS Code) may launch with a different PATH than your terminal.

---

When to Escalate

Contact support at [email protected] if:

• You have placed the binary in a standard location (/usr/local/bin) and it still returns command not found.
• You are on a managed machine where sudo mv is not available and your organization controls PATH.

Include the output of:

echo $PATH
uname -a
ls -la /usr/local/bin/canopy 2>/dev/null || echo "not found"