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.

Related MCP server: python-mcp-server

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 <project>/.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, not a security sandbox. Project code may still access the filesystem, network, or subprocesses and may have import-time side effects.

• The simulator prefers <project>/.venv or venv, then the same directories in the parent project. Use python_executable to choose explicitly and check the returned worker metadata when imports fail.

Evidence

The measured local latency suite covers three pinned projects with 148–1,650 Python files and 4,468–16,960 indexed functions. It reports cold analysis, first and warm search latency, and eight-worker throughput; the raw result is committed with the benchmark artifacts.

The model-backed evaluation covers frozen tasks and hidden rubrics for Google ADK, LangGraph, and FastAPI. It compares built-in code exploration plus logic_flow against the same built-in exploration alone. Across 54 isolated sessions, three paired repetitions produced a suite-wide median of 22.95% fewer server-reported total tokens. All 27 treatment sessions completed the required tool call, providing direct evidence that one CodeCanvas tool adds meaningful value without replacing the agent's existing search tools. Uncached input plus output increased by a median 0.78%, and the answers are not yet blind-graded, so this is not yet an efficiency-at-equal-quality or billing-cost claim.

See the full methodology, result tables, reproduction commands, and audit artifacts.

Development

git clone https://github.com/donggyun112/codecanvas.git
cd codecanvas/core
uv sync --extra dev
cd ..
core/.venv/bin/python -m pytest

The package source lives under core/. The root test configuration runs both the product tests in tests/ and the package-level tests in core/tests/.

Issues and focused reproduction cases are welcome: https://github.com/donggyun112/codecanvas/issues.

License

CodeCanvas MCP is open-source software licensed under the MIT License.