MCP Server Won't Start

Symptoms

• Your MCP client (Claude, Cursor, etc.) reports it cannot connect to Canopy.
• Error messages such as “failed to start MCP server”, “spawn failed”, or “connection refused”.
• The client connects but all tool calls return empty results or errors.
• canopy serve starts from the command line but the client still cannot see the tools.

---

Likely Causes

Cause	Indicator
Wrong path to the canopy binary in .mcp.json	”spawn failed” or “command not found”
canopy binary not in the shell’s PATH	Works from terminal but not from client
Repository has not been indexed yet	Tools call but return “index not found”
.mcp.json points to the wrong repository path	Tools return results for the wrong repo
Community Mode restriction	MCP server refused without license (canopy serve exits with an error)

---

Step-by-Step Fix

Step 1: Confirm canopy is in your PATH

which canopy
canopy --version

Expected output:

/usr/local/bin/canopy
canopy 1.3.0

If which canopy returns nothing, see Client Can’t Find canopy.

Step 2: Check your .mcp.json configuration

Your MCP client reads server definitions from .mcp.json (or an equivalent config file). A typical Canopy entry looks like:

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

Verify:

• "command" is "canopy" or an absolute path to the binary (e.g., "/usr/local/bin/canopy").
• "args" includes the absolute path to the repository you want to analyze. Relative paths may not resolve correctly depending on how the client launches the server.
• The repository path exists and contains a .git directory.

Step 3: Verify the repository is indexed

The MCP server requires an existing index. Run:

canopy status --repo /absolute/path/to/your/repo

If you see “repository not found”, index it first:

canopy index /absolute/path/to/your/repo --with-search

Then restart your MCP client.

Step 4: Test the server manually

Run canopy serve from the command line to see if it starts cleanly:

canopy serve /absolute/path/to/your/repo

Expected output:

canopy MCP server started for /absolute/path/to/your/repo
Listening on stdin/stdout (JSON-RPC 2.0)

If you see an error here, the problem is in Canopy itself (not the client config). Common errors:

• index not found — run canopy index first
• license required — Community Mode: MCP server requires a license (see below)

Step 5: Community Mode restriction

Starting with v1.3.0, canopy serve in Community Mode (no license) refuses to start the MCP server. If you see this error, you have two options:

1. Activate a license: Run canopy activate <key> or start a trial at https://canopy.ironpinelabs.com/pricing.
2. Use CLI commands directly: Community Mode supports canopy search, canopy health, and canopy status from the command line without the MCP server.

Step 6: Use absolute paths

Some MCP clients launch servers from a different working directory than your terminal. Use absolute paths in .mcp.json:

{
  "mcpServers": {
    "canopy": {
      "command": "/usr/local/bin/canopy",
      "args": ["serve", "/Users/yourname/repos/my-project"]
    }
  }
}

Replace /usr/local/bin/canopy with the output of which canopy.

Step 7: Restart the MCP client

After any change to .mcp.json or after running canopy index, restart your MCP client completely. Most clients do not detect configuration changes dynamically.

---

When to Escalate

Contact support at [email protected] if:

• canopy serve <path> starts cleanly from the terminal but the client still cannot connect.
• Tool calls return unexpected errors after the server is confirmed running.

Include the output of:

canopy --version
canopy status --repo /path/to/repo
canopy license