Codecanvas

CodeCanvas MCP

Understand an unfamiliar Python system before spending thousands of tokens reading it file by file.

CodeCanvas is a local static-analysis Model Context Protocol server for Python. It turns project-wide call paths and control flow into compact, citation-ready answers about branches, callers, callees, side effects, and change impact.

The benchmark now spans pinned revisions of Google ADK, LangGraph, and FastAPI. On an Apple M4 Pro, measured cold analysis ranged from 4.38s to 61.62s, and median warm find_symbols latency ranged from 48.264ms to 293.778ms across those repositories. In a controlled 54-session agent suite, both conditions kept the same built-in code-search tools; the treatment added only logic_flow. That single addition used a median 22.95% fewer total tokens across three paired repetitions, demonstrating meaningful incremental value on top of ordinary code exploration. Uncached tokens increased by 0.78%, and the answers are not yet blind-graded. See the methodology, full tables, and limitations.

Use it to answer questions such as:

• Who calls this function, directly or transitively?
• What can this function reach, and where do side effects happen?
• Under which guards can this return or exception occur?
• Does this source really reach that target in the requested mode?
• Which API routes, scripts, or public exports are affected by a diff?

CodeCanvas is Python-only and requires Python 3.10 or newer.

See the difference

Ask one question:

Use logic_flow on UserService.update_user. Show its branches, outcomes,

downstream effects, and evidence quality.

Excerpt from the actual response on the included FastAPI sample:

{

"function": "app.services.user_service.UserService.update_user", "source": "app/services/user_service.py:13", "flow": [ "15 user = await self.user_repo.find_by_id(...)", "16 if user is None:", "17 → return None", "18 → return await self.user_repo.update(user_id, user)" ], "outcomes": [ {"at": 17, "detail": "None", "guards": ["user is None"]}, {"at": 18, "detail": "await self.user_repo.update(user_id, user)", "guards": []} ], "downstream": [ { "function": "app.repositories.user_repo.UserRepository.find_by_id", "location": "app/repositories/user_repo.py:13", "effects": ["db"] }, { "function": "app.repositories.user_repo.UserRepository.update", "location": "app/repositories/user_repo.py:18", "effects": ["db"] } ], "evidence_grade": "inferred", "safe_to_summarize": false, "response_guidance": "Do not turn inferred call edges into unconditional claims." }

That single response exposes the early return, success path, downstream database work, exact source locations, and how cautiously the agent may summarize the result.

Quick start

Install uv if uvx is not already available. The repository includes one shared plugin package with native manifests for both Claude Code and Codex. Install it from the CodeCanvas marketplace:

# Claude Code

claude plugin marketplace add donggyun112/codecanvas claude plugin install codecanvas@codecanvas

Codex

codex plugin marketplace add donggyun112/codecanvas codex plugin add codecanvas@codecanvas

Both plugins start uvx codecanvas-mcp and expose the complete tool catalog. See the plugin package for local-checkout testing and validation commands.

If your client does not support plugins, register the server directly. For Claude Code:

claude mcp add codecanvas -- uvx codecanvas-mcp

That command exposes the complete tool catalog. Keep the full catalog enabled when your MCP client supports on-demand tool discovery or tool search: the client can load the relevant schemas only when they are needed, so the other CodeCanvas tools remain available without paying their schema cost on every model request.

[mcp_servers.codecanvas]

command = "uvx" args = ["codecanvas-mcp"]

If your client eagerly injects every enabled tool schema into every model request, use this compatibility profile instead:

[mcp_servers.codecanvas]

command = "uvx" args = ["codecanvas-mcp"] enabled_tools = ["logic_flow", "who_calls", "call_tree"]

The three-tool allow-list is a fallback for eager-schema clients, not a recommendation to discard the rest of CodeCanvas. For another MCP client, use the equivalent stdio configuration:

{

"mcpServers": { "codecanvas": { "command": "uvx", "args": ["codecanvas-mcp"] } } }

Pass an absolute project_path on the first tool call. CodeCanvas remembers the last explicitly selected project for the rest of the server session.

With the complete catalog enabled, project_status reports candidate analysis roots for nested Python projects. Compact-profile users should pass the intended nested root explicitly.

Teach your agent when to use it

Adding tools does not guarantee that an agent will choose them at the right time. Put a short instruction like this in AGENTS.md, CLAUDE.md, or the equivalent file used by your coding agent:

## Code analysis

Use CodeCanvas before text search when you need to know:

• how a Python function branches, returns, and produces side effects;
• who calls it directly or transitively;
• what it reaches downstream through project-internal calls.

Pass project_path once, then reuse the active project. Treat safe_to_summarize: false, inferred edges, ambiguity, and truncation as qualifications rather than unconditional facts.

Start with logic_flow. Use who_calls for upstream impact and call_tree for a deeper downstream trace.

Then ask your agent naturally:

Use logic_flow first to understand checkout without repeated source searches.

What calls UserService.update_user, up to three hops? What does checkout reach downstream, including HTTP or database effects?

With the complete catalog enabled, CodeCanvas can also answer:

List the entrypoints in this project.

Under exactly what conditions can authenticate raise? Verify that dry-run publish reaches _call_api. Analyze the impact of the current diff.

Why not just grep or an LSP?

CodeCanvas complements both. It is for behavioral questions that otherwise require repeated searches and manual reconstruction.

What makes the answers trustworthy

Static analysis is not runtime truth, so CodeCanvas makes uncertainty visible instead of hiding it.

Every successful MCP response identifies the selected analysis_root and includes metadata that helps an agent decide how strongly it may state the result:

• evidence_grade describes the strength of the resolved evidence.
• inferred_edge_count and ambiguous_calls expose uncertain call edges.
• truncated says whether the bounded response omitted results.
• safe_to_summarize says whether the result supports an unconditional claim.
• response_guidance explains how to qualify a result when it does not.

verify_claim goes further by combining candidate call paths with branch and return/raise guards. It returns true, false, or uncertain; unsupported qualifiers and inferred-only paths cannot silently become a definite true.

Tools

Discover and understand

Follow behavior and assess change

Reproduce state-shaped bugs

Large result sets are capped. Use each tool's filter, kind, path, depth, or pagination arguments to narrow the answer before treating it as complete.

How it works

1. Select a project. CodeCanvas resolves and remembers an explicit Python project root. Ambiguous nested roots must be selected rather than guessed.
2. Build structural indexes. Python AST analysis builds a project-wide call graph and per-function control-flow data. Extractors add FastAPI routes and Depends() chains, scripts, generic function entrypoints, and package exports.
3. Reuse compatible analysis. The call graph and entrypoints are cached in /.codecanvas/; an in-process builder is reused during the MCP session.
4. Project compact answers. Each MCP tool queries the shared analysis and returns bounded results with origin, evidence, ambiguity, and truncation metadata.

The default analysis limit is 5,000 Python files. Tune large-project behavior with:

Safety and limitations

• CodeCanvas analyzes Python source; it does not model every possible dynamic import, monkey patch, reflection path, or runtime value.
• Inferred and ambiguous edges are reported as qualifications, not promoted to definite evidence.
• Static-analysis tools read project files and write the local .codecanvas/ cache. No remote CodeCanvas service is required.
• simulate_state_transition is different: it imports and executes trusted project code in a separate process. It is isolation for focused repros, n