How Canopy Gives Claude Code Structural Understanding

Note: Canopy is in pre-release development. Purchase and download links aren’t live yet. Join the waitlist to be notified at launch.

Here is what makes Canopy structurally different from other MCP-based codebase tools. This post walks through the three-layer architecture that makes AI agents materially smarter — not by giving them a smarter model, but by giving them structured information they can actually reason about.

Without Canopy, Claude Code gets a request to “refactor the payment flow” and starts reading files. It reads payments.ts, then billing.ts, then checkout.ts, then it guesses at related files and reads those too. Forty files later, it makes the changes and hands them back. Two call sites got missed. Three tests will fail at CI. The developer finds this out the hard way.

With Canopy, the same request looks like this: Claude Code asks one question — ‘what depends on src/utils/payments.ts?’ — gets back a cited list of 12 dependent files, makes targeted changes to all 12, and asks ‘are there import cycles?’ before handing the work back. The refactor is clean on the first pass.

That difference is not about the model being smarter. It is about the model having access to structured information it could not otherwise reason about. This post explains exactly how Canopy delivers that information and, more importantly, how it teaches the agent to ask for it.

The Problem With MCP Servers That Just Expose Tools

The MCP protocol lets you register tools with an AI agent. The agent can call those tools. This is powerful in theory. In practice, most MCP servers expose tools and then get out of the way — the agent has to figure out when to call what and why.

An agent with access to a search_codebase tool still has to know: “I should call this before I modify a file.” An agent with access to a check_imports tool still has to know: “I should call this after I make changes.” Nothing in the MCP spec teaches the agent those behaviors. The tool descriptions help, but they are read once and mostly forgotten as the context window fills up.

We know this failure mode intimately, because we shipped it. Canopy v1 exposed a 31-tool catalog — search, AST, graph, git, workflow tools, each with a carefully written description. In a controlled benchmark, agents handed that catalog spent 2.3×–5.8× more than agents with plain shell tools. The catalog itself was the overhead: more descriptions to hold in context, more intermediate results to interpret, more chances to pick the wrong tool. Canopy 2 deleted all 31 and replaced them with one: canopy_answer.

The rest of this post is how one tool guides an agent better than thirty-one did — at three layers.

Layer 1: Server Instructions

When an MCP client (Claude Code, Cursor, any MCP host) connects to Canopy, Canopy sends a set of behavioral rules in the initialize response. These rules are injected into the agent’s system prompt automatically — the user does not have to configure anything.

Here is what those instructions look like (condensed):

You have access to Canopy via a single tool: canopy_answer.
Ask any code-intelligence question in natural language.

PHRASING PICKS THE RECIPE: name the entity TYPE and backtick
paths/symbols so the classifier locks on — a vague question
falls back to a weaker semantic search.

High-value shapes:
  'where is the function `Sym` defined?'         (locate)
  'what does `path` do?'                         (explain a file)
  'what depends on `path`?'                      (blast radius)
  'what should I know before editing `path`?'    (pre-edit dossier)
  'who last changed `path`?'                     (ownership)
  'what tests cover `path`?'                     (coverage)
  'is `path` dead code?'                         (wiring)
  'are there import cycles?'
  'architecture overview'

Call it once and relay its answer.

The key design choice: the instructions teach phrasing, not procedure. v1’s instructions had to teach when to call which of 31 tools — rules the agent gradually forgot as its context filled. v2’s instructions teach one durable habit: name the entity type, backtick the path or symbol, ask. Framing matters — an agent that knows ‘what depends on path?’ is a recognized question shape will reach for it at exactly the moment it is about to rename something.

Layer 2: The Deterministic Router

The second layer is what happens to the question. Canopy does not hand your question to an LLM to figure out what you meant. Routing is a deterministic, corpus-validated classifier that maps the question to a recipe — locate, extract, explain, dependents, imports, ownership, coverage, wiring, architecture. It scores 360/360 on its labelled regression corpus, makes no model call, and needs no network. Routing costs nothing, adds no latency floor, and never guesses differently on Tuesday.

The recipe then runs the whole chain server-side. ‘what should I know before editing src/core/license.rs?’ does not return raw data for the agent to assemble — it returns the pre-edit dossier as one cited answer. Condensed example:

Q: what should I know before editing `src/core/license.rs`?

A: 47 files depend on src/core/license.rs — 4 directly:
   cli/activate.rs, cli/serve.rs, mcp/server.rs, tools/workflow.rs.
   Test coverage is low (34%). Last changed 2026-04-14 by
   dev@example.com; 8 changes in the last 30 days.
   No import cycles involve this file. 2 exports appear unused.

The agent reads this and adjusts its plan. A 47-dependent file at 34% coverage warrants more careful changes than a leaf module with zero dependents and 90% coverage — and the dossier says so in one breath, instead of across six tool calls the agent may or may not think to make.

One more router behavior worth calling out: when nothing in the index clears the relevance floor, Canopy answers “No strong match in this repository for …” rather than relaying tangential files. An empty answer is signal, not noise — the agent learns it can trust a miss as much as a hit.

Layer 3: One Description That Teaches Phrasing

The third layer is the tool description itself. MCP tool descriptions are usually a sentence or two explaining what the tool does. Canopy’s is a mini-pedagogy — and because there is exactly one tool, it is the only description the agent ever has to absorb.

Compare a naive description:

canopy_answer — Answers natural-language questions about the codebase.

With Canopy’s actual description (condensed):

PHRASING PICKS THE RECIPE: name the entity TYPE and backtick paths/symbols so the classifier locks on. Shapes: ‘where is the function/struct/class Sym defined?’ (locate); ‘what depends on path?’ or ‘what calls Sym?’ (dependents / blast-radius); ‘what should I know before editing path?’ (pre-edit dossier); ‘what tests cover path?’ (coverage); ‘is path reachable / dead code?’ (wiring); ‘who last changed path?’ (ownership); ‘architecture overview’. A precise shape beats a vague ‘how does X work’. Runs the whole chain server-side; saves 3–5 round-trips vs primitive tool chains.

The second description teaches the agent when to ask, how to phrase, and what it saves. In v1, that pedagogy was spread across 31 competing descriptions; agents read them once and forgot most of them. In v2 it is one block, and every question the agent asks reinforces the same phrasing habit instead of diluting it.

A Real Agent Transcript

Here is what a Canopy-assisted refactor session looks like in Claude Code, condensed:

User: Rename the LicenseError enum to LicenseValidationError throughout the codebase.

Claude: I'll trace the blast radius first.

[canopy_answer: "what calls `LicenseError`?"]

9 files reference LicenseError directly:
  - canopy-cli/src/commands/activate.rs (lines 23, 31, 45)
  - canopy-cli/src/commands/license.rs (lines 12, 18)
  - canopy-mcp/src/tools/workflow.rs (lines 67, 89, 112)
  - canopy-mcp/src/tools/health.rs (line 44)
  - canopy-core/src/license.rs (definition, lines 8-14)
  + 4 test files

[canopy_answer: "what should I know before editing `canopy-core/src/license.rs`?"]

Pre-edit dossier: 47 dependents total, low coverage (34%).
Proceeding with the rename across all 9 direct references.

[makes changes to all 9 files]

[canopy_answer: "are there import cycles?"]

No cycles introduced. All 9 references updated consistently.
Rename is complete and clean.

Without Canopy, the same task would likely miss some of the 9 files — agents reading the codebase via file listing and search typically hit 5-6 of them and miss the rest. With Canopy, the list is complete because the dependents recipe is doing AST-level symbol tracking, not text search.

Why Self-Hosted Matters for This Architecture

The instruction-and-router design only works if answers come back fast enough that asking is never a chore. Two things keep it fast. Routing is deterministic — no LLM call, no network, nothing to wait on before the recipe starts. And the index is local — SQLite on your machine — so the recipe reads the graph directly, with no round-trip to a cloud API, no authentication overhead, no rate limiting, and no token cost for the analysis itself.

If Canopy were a cloud service, every question would pick up network latency and rate limits — and agents, like the people who supervise them, quietly stop using tools that feel slow. A refactor that should open with a blast-radius question opens with a guess instead.

Self-hosted is not just a privacy story. It is the reason the agent keeps asking.

Join the Waitlist

If you use Claude Code, Cursor, or any MCP-compatible agent and this three-layer architecture sounds useful, join the waitlist — we’ll email you when Canopy is available for download.

Questions and technical feedback welcome at support@gulfshieldtech.com and GitHub Discussions.