137× less context: anatomy of one MCP query

Take an ordinary task: "find everything that calls validateSession, I'm about to change its signature." Watch how a capable agent does it without a graph, and you'll see the same shape every time — and a token bill that explains a lot about why long sessions get expensive.

The grep-and-read path

With only a search tool and a file reader, the agent fans out. It greps for the name and gets forty hits across twenty files — definitions, comments, similarly-named things, strings. It can't tell which are real call sites from the match alone, so it reads files. Whole files, because a 30-line window rarely contains the answer. Each read drops hundreds or thousands of lines into context. By the time it's confident it has the callers, it has pulled tens of thousands of tokens of mostly-irrelevant source through the model — and most of that is structure it could have looked up instead of re-derived.

The MCP path

SpecShip runs as an MCP server over the same local graph. The agent doesn't search text; it asks the index a question. "Callers of validateSession" returns a handful of qualified symbols with their file and line — the actual edges, already resolved, no false positives to read past. The answer is small because it's the answer, not the haystack the answer was hiding in.

src/api/login.ts:authenticate          // calls
src/api/refresh.ts:refreshToken         // calls
src/middleware/guard.ts:requireSession   // calls

One round-trip, a few hundred tokens, zero files read. And because the graph carries provenance, the agent knows which of those edges are hard call edges and which were synthesized from a dynamic dispatch — information a text search can't give it at any token price.

One tool, used first

The most-used tool isn't a clever new verb — it's specship_explore, which takes a bag of symbol names and returns their verbatim source grouped by file, with the call path among them surfaced. It's Read-equivalent for the symbols that matter, in one call, so the agent stops the instant the answer is sufficient instead of drilling file by file. The whole design target is exactly that: make the structured answer good enough that the agent never falls back to reading.

Why it compounds

A single query saved is nice. The real effect is across a session: every structural question answered from the index is a file not read, which is context not spent, which is a turn not taken. The savings stack, and they stack hardest on exactly the long, multi-step tasks where agents are otherwise least efficient. Store the structure once; query it forever.