Code graph MCP server for AI coding agents
A code graph MCP server indexes a codebase into a structured knowledge graph — symbols, definitions, call hierarchies, imports, and framework routes — and serves targeted slices to AI coding agents over the Model Context Protocol.
Without a code graph, an AI agent running in Claude Code, Cursor, Codex, or Windsurf relies on grep, find, and repeated file reads. Every turn pulls thousands of lines of source code into the prompt window. A code graph server changes that relationship: the repository is indexed once locally, and the agent queries precise relationships instead of re-reading raw files.
Without code graph: Prompt -> grep / read_file -> 10,000+ raw tokens loaded per turn
With code graph: Prompt -> graph query -> exact subgraphs (definitions, callers, routes)
Why AI agents need persistent graph context
Every turn in an agentic coding session pays for the entire preceding conversation history. When an agent opens files to locate a function or trace an import, those lines remain in the prompt context until the session ends.
A persistent code graph replaces file scans with graph queries:
- Cost scales with the answer, not the repository. Reading files scales with the size of the repository. Graph queries (
find_symbol,find_usages,get_change_impact) scale with the size of the returned subgraph. - Measured context reduction. In real benchmarks, graph-assembled context reduces input token usage by a median 72.7% to assemble pull-request review context across 60 open-source pull requests in 6 repositories (read the PR context benchmark, or explore 7 tactics to cut Claude Code token usage). Blind evaluation confirms comprehension at parity: 67% understood rate against naive file loading’s 65% (at 0.80 vs 0.58 false positives per PR; see quality preregistration).
- Freshness without rebuilds. File watchers detect edits with a 300 ms debounce, re-parsing only changed files and updating edge tables in an embedded SQLite database.
How trace-mcp implements the code graph
trace-mcp is a local-first code graph MCP server built around four architectural choices:
- Polyglot tree-sitter parsing: Parsers for 81 programming languages compile into the binary, resolving symbols, classes, functions, and import chains without requiring language servers or build toolchains (view language matrix).
- Framework-aware semantic edges: Web applications do not live in isolated ASTs. trace-mcp resolves route-to-controller, controller-to-template, and model-to-table relationships across 88 frameworks, including Laravel, Next.js, Django, Rails, Spring, and FastAPI (supported frameworks).
- Zero-overhead local storage: All graph nodes, edges, and FTS5 search indices live in an embedded SQLite database on your machine. For how resident memory and caches are capped, see daemon memory. No hosted services, no background daemons requiring cloud accounts, and your source code never leaves your machine (local privacy guarantee).
- Controlled schema footprint: An MCP server that advertises dozens of tools consumes thousands of tokens before the agent asks its first question. trace-mcp uses role presets to expose roughly 2K tokens of tool schemas on session start, while keeping extended tools accessible dynamically via
load_tools(tools reference, tool index).
The code graph MCP ecosystem
Different tools approach codebase context from distinct angles:
| Approach | Representative project | Mechanism | Trade-off |
|---|---|---|---|
| Prompt packing | Repomix | Concatenates repository source into a single compressed prompt artifact. | Fast setup, but computes no edges and repays full file costs on every turn. trace-mcp vs Repomix |
| LSP proxy | Serena | Bridges IDE language servers directly into MCP tool calls. | Compiler-grade type precision, but requires active language toolchains and maintains no persistent graph. trace-mcp vs Serena |
| Single-tool graph | codegraph | Exposes a single explore tool by default to minimize advertised schema tokens. |
Low schema token cost, but navigation only — no write path or framework edges. trace-mcp vs codegraph |
| Broad grammar graph | codebase-memory-mcp | Compiles 162 vendored grammars into an incremental graph. | Broad syntax support, but no framework routing or refactoring operations. trace-mcp vs codebase-memory-mcp |
| SCIP-driven graph | CodeGraphContext | Orchestrates eleven external Sourcegraph SCIP indexers into graph snapshots. | External indexer pipelines, but requires external binaries and complex backend choices. trace-mcp vs CodeGraphContext |
| Review graph | code-review-graph | Tracks incremental changes with empty-result uncertainty explanations. | Specialised for review navigation, but advertises 29 tools without preset filtering. trace-mcp vs code-review-graph |
| Hybrid vector-AST graph | SocratiCode | Combines Qdrant vector embeddings with ast-grep in Docker. | Semantic vector search, but requires Docker runtime and lacks framework routing. trace-mcp vs SocratiCode |
| Meta-dispatch graph | jCodeMunch | Fronts 90+ Python tools through “The Counter” meta-dispatch (order, menu, route). |
Dual-Use license (non-commercial only) and regex route detection. trace-mcp vs jCodeMunch |
| Native Rust libSQL graph | TokenSave | Native Rust binary with libSQL storage, multi-branch indexing, and subprocess isolation. | Advertises 85+ tools by default (~12-15K schema tokens) with no framework routing. trace-mcp vs TokenSave |
| Runtime buffer truncation | Context Mode | Intercepts and truncates CLI execution buffers before prompt injection. | Focuses on runtime stdout/stderr pruning; maintains no persistent semantic code graph. trace-mcp vs Context Mode |
| Knowledge graph Cypher | GitNexus | Constructs code knowledge graph in embedded Kuzu graph DB querying via raw Cypher strings. | Non-commercial PolyForm license, requires local C++ toolchain build, and exposes unvalidated Cypher queries. trace-mcp vs GitNexus |
| LLM concept summaries | Graft | Generates plain-language subsystem and concept explanations in markdown files via LLM. | Requires external LLM API keys and model calls for all node generation; no relational graph traversal. |
| RDF multi-layer CCG | Narsil-MCP | Emits 4-layer progressive disclosure Code Context Graph (CCG) datasets in RDF/N-Quads. | Advertises ~90 tools without role presets; complex semantic web RDF formats rather than lightweight JSON. |
| Packing vs indexing | Repomix vs codegraph | Side-by-side comparison of full-file prompt packing against single-tool graph exploration. | Evaluates static context serialization against interactive graph queries. Repomix vs codegraph |
For a comprehensive feature-by-feature breakdown across 20+ tools, see the code graph comparisons hub.
Getting started
Install trace-mcp in your project root:
npx trace-mcp init
The init command inspects your repository, detects your frameworks and languages, sets up client configurations for Claude Code, Cursor, or Windsurf, and indexes your codebase into a local .trace/ database. See what trace init installs for a complete breakdown of guard hooks, routing blocks, and client configurations written to your project.
- Explore all available tools: Tools Reference and the alphabetical Tool Index
- Review configuration and preset options: Configuration Guide
- Inspect architecture and storage contracts: Architecture Documentation
Catalogue: Articles / concepts
Last updated: October 19, 2026