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 calls to the canopy_answer tool return empty results or errors.
• canopy serve starts from the command line but the client still cannot see the canopy_answer tool.

---

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	canopy_answer responds but reports a missing index
.mcp.json points to the wrong repository path	Answers describe the wrong repo

---

Step-by-Step Fix

Step 1: Confirm canopy is in your PATH

which canopy
canopy --version

Expected output:

/usr/local/bin/canopy
canopy 2.0.0-alpha.1

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

Step 2: Check your .mcp.json configuration

Canopy prints the exact wiring snippet for your client — copy it instead of writing the block by hand:

canopy serve /absolute/path/to/your/repo --print-mcp-config

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"]
    }
  }
}

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

Answers require an existing index. Run:

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

The Index section of the report shows status: indexed when the repo is ready. If it shows status: not indexed, index it first:

canopy index /absolute/path/to/your/repo

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

A clean start writes nothing to stdout (stdout is reserved for JSON-RPC frames; printing to it would corrupt the protocol). The startup banner only appears in the structured log stream on stderr — surface it with -v:

canopy serve /absolute/path/to/your/repo -v 2>&1 1>/dev/null

Expected log line:

INFO canopy-mcp server started for repo <id>

If canopy serve exits immediately, the problem is in Canopy itself (not the client config). Look at stderr for the exit reason. If the server runs but answers report a missing index, run canopy index first (Step 3).

Step 5: 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 6: 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 support@gulfshieldtech.com if:

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

Include the output of:

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