CGraph exposes eight MCP tools that let a coding agent navigate a codebase as a graph instead of grepping it: graph_query, graph_explain, graph_impact, graph_path, graph_context, graph_update, graph_status, and graph_shutdown. This post walks through what each one answers and when an agent should reach for it.
Why MCP tools instead of grep
A coding agent that reads code by searching sees text, not the graph of files, symbols, and references the text encodes. Every request re-derives that structure from scratch, and the answer is only as good as the search terms. CGraph extracts the structure once, keeps it warm in a per-project daemon, and serves it to the agent over the Model Context Protocol. The agent asks precise structural questions and gets precise answers back — file:line, not a wall of matches.
The tools route through the same daemon operation handler as the CLI, so an agent gets exactly the semantics a human at the terminal does. There's one place to reason about correctness and no drift between "what the CLI does" and "what the agent sees."
The eight tools
CGraph's MCP server (cgraph-mcp) exposes these eight tools, grouped by the kind of question they answer.
Understanding what's there
| Tool | Answers |
|---|---|
graph_query | Find nodes matching a query. |
graph_explain | Explain a node and its role. |
graph_query is the entry point — the agent's equivalent of "find the thing." graph_explain goes one level deeper: given a node, it describes what that node is and the role it plays in the graph. In practice an agent pairs them: query to locate Parser, then explain to understand what it is and where it fits.
Understanding relationships
| Tool | Answers |
|---|---|
graph_impact | The transitive blast radius of a change. |
graph_path | The shortest path between two symbols. |
These are the tools that grep cannot cheaply replicate. graph_impact returns the transitive set of nodes reachable from a change — everything that could break if you touch a given symbol. Doing that by hand is a multi-round manual trace agents frequently skip; as a single query it's the standout capability (see Impact analysis in ~10ms). graph_path answers "how do these two modules connect?" by returning the shortest path between two symbols — useful when an agent needs to understand how a request flows from one part of the system to another.
Feeding the agent context
| Tool | Answers |
|---|---|
graph_context | A packed, budgeted neighborhood for the agent. |
graph_context is the tool built specifically for LLMs. It gathers a neighborhood around a node and packs it to a token budget — knapsack-style, fitting the most relevant nodes into the space the agent can afford. It supports two gather modes: fixed packs the whole k-hop neighborhood, while adaptive keeps the full 2-hop core and expands the third hop only along query-relevant nodes. The response reports what happened — a reach summary alongside the gather and packing mode — so the retrieval is inspectable rather than a black box. See Budgeted context for LLMs for how the packing works.
Managing the graph's freshness and lifecycle
| Tool | Answers |
|---|---|
graph_update | Fold in changes / trigger a rescan. |
graph_status | Daemon and graph health. |
graph_shutdown | Stop the daemon. |
The graph is the agent's durable memory of the codebase, and these three tools keep that memory honest. graph_status reports daemon and graph health — including, while a build is in progress, a graph_state: "building" signal so the agent can tell "not ready yet" from "genuinely empty." graph_update folds in edits or triggers a rescan when the agent has changed source and needs the graph current. graph_shutdown stops the daemon when the session is done.
When an agent should reach for which
The docs map common questions to tools directly:
| The agent wants to know | Reach for |
|---|---|
"What is Parser and where is it used?" | graph_query, then graph_explain |
| "What breaks if I change this signature?" | graph_impact |
| "How do these two modules connect?" | graph_path |
| "Give me the relevant context, within budget." | graph_context |
| "Is the graph up to date?" | graph_status, then graph_update |
A natural flow through a task looks like: graph_query to find the symbol, graph_explain to understand it, graph_impact to see what a change reaches, graph_context to pull a budgeted neighborhood into the prompt, then graph_update after editing so the next question sees the new state.
Getting them into your agent
Registering CGraph is a one-line MCP setup. With Claude Code:
claude mcp add cgraph -- "$PWD/build/default/src/mcp/cgraph-mcp"
cgraph-mcp speaks newline-delimited JSON-RPC 2.0 over stdio (protocol version 2024-11-05) and resolves the project root from a --root flag, then CLAUDE_PROJECT_DIR, then the working directory. Because Claude Code sets CLAUDE_PROJECT_DIR and CGraph can discover graphd next to its own binary, the tools work with minimal configuration — often no flags at all. Full setup for Claude Code, Codex, and Cursor is in AI Agent Integration.
The payoff
An agent without a graph re-derives structure from search on every turn. With these eight tools it asks precise questions against a warm, persistent model — spending fewer tokens rediscovering the codebase and more on the actual task. (That token comparison is a self-run benchmark on CGraph's own repository in a Debug build — read the caveats before quoting a figure.)
If you're weighing this against other code-intelligence approaches, see code graphs vs LSP vs ctags — the code graph is the only one of the three built to hand a whole-project model to an agent within a token budget. To try the tools yourself, read the code on GitHub or start with the MCP integration docs.