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 70.5% to assemble pull-request review context across 60 open-source pull requests in 6 repositories (read the PR context benchmark).
- 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 87 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. No hosted services, no background daemons requiring cloud accounts, and no API keys.
- 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).
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 |
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.
- Explore all available tools: Tools Reference
- Review configuration and preset options: Configuration Guide
- Inspect architecture and storage contracts: Architecture Documentation
Last updated: September 7, 2026