Agent tools (MCP)

arcade-agent ships an MCP server (arcade-mcp) with 24 tools. Fifteen cover the full analysis pipeline — ingest, parse, recover an architecture, detect smells, compute metrics, compare versions, and report on the result; four are task-shaped context tools designed for the questions agents actually ask mid-edit; and five form an architecture guardrail that checks code against an architecture you write down. The guardrail tools arrive in v0.4.0 (unreleased at the time of writing); the 0.3.0 release on PyPI has the other 19.

Using Claude Code? There’s also a packaged Claude Code skill that runs the whole pipeline from a natural-language request and produces finished reports — including an architecture guardrail for agents writing code. The MCP server and the skill are complementary, not alternatives.

Setup

Agents evaluating this tool can fetch the machine-readable docs index at https://arcade-agent.dev/llms.txt rather than crawling this site page by page.

All five clients below point at the same server: uvx fetches and runs arcade-agent with the mcp extra (required — arcade-mcp fails to start without it) on first launch, so there’s nothing to pre-install. Only the file path and the top-level JSON key differ per client.

Claude Code — .mcp.json

{
  "mcpServers": {
    "arcade-agent": {
      "command": "uvx",
      "args": ["--from", "arcade-agent[mcp]", "arcade-mcp"]
    }
  }
}

Cursor — ~/.cursor/mcp.json

{
  "mcpServers": {
    "arcade-agent": {
      "command": "uvx",
      "args": ["--from", "arcade-agent[mcp]", "arcade-mcp"]
    }
  }
}

Claude Desktop — claude_desktop_config.json

{
  "mcpServers": {
    "arcade-agent": {
      "command": "uvx",
      "args": ["--from", "arcade-agent[mcp]", "arcade-mcp"]
    }
  }
}

VS Code — .vscode/mcp.json

{
  "servers": {
    "arcade-agent": {
      "command": "uvx",
      "args": ["--from", "arcade-agent[mcp]", "arcade-mcp"]
    }
  }
}

Windsurf — ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "arcade-agent": {
      "command": "uvx",
      "args": ["--from", "arcade-agent[mcp]", "arcade-mcp"]
    }
  }
}

The tools

Tool	What it answers	When the agent calls it
ingest	Where’s the source, and what’s actually in scope?	First — before anything else. Accepts a git URL or local path, auto-detects the source root, and filters out test/vendor/build directories.
parse	What are the entities and dependency edges in this codebase?	Right after ingest, before recover, summarize, or any tool that needs a dep_graph.
analyze	Run the whole pipeline — ingest, parse, recover, smells, metrics — in one call.	When starting fresh on a repo and one round-trip is worth more than stage-by-stage control; returns per-stage session IDs (even on partial failure).
recover	How do these entities group into components (pkg/wca/acdc/arc/limbo)?	After parse, before the smell/metric/query/explain tools that need an architecture.
detect_smells	Which components have a dependency cycle, concern overload, scattered functionality, or link overload?	After recover, when auditing architecture health.
compute_metrics	How cohesive and coupled is this architecture (RCI, TurboMQ, BasicMQ, connectivity, coupling ratios)?	After recover, to quantify what detect_smells flagged qualitatively.
compare	What changed between two recovered architectures — components added, removed, split, or merged?	Comparing two versions (e.g. two commits), matched via the Hungarian algorithm.
query	Ad hoc structural questions: component_of, dependencies, dependents, entities, most_coupled, summary, largest.	Mid-investigation, once an architecture and dep_graph exist, for one specific follow-up.
visualize	How do I get a shareable report or diagram (HTML, DOT, JSON, RSF, Mermaid) of this analysis?	End of a pipeline run, to hand a human-readable artifact to someone else.
summarize	What does this codebase — or one package — look like at a glance: structure, dependency hotspots, entry points?	First orientation pass on a repo, or drilling into one package via focus.
explain_component	What does this one component do: responsibility, entities, public API surface, dependencies, cohesion?	Drilling into a single component surfaced by recover, detect_smells, or query.
find_relevant	Which entities relate to this natural-language topic?	Searching code by concept or keyword rather than an exact name.
api_surface ★	What is safe to call on this component from outside?	When wiring into unfamiliar code.
diff_impact ★	What breaks if these files change?	Before and after editing — blast radius.
context_for_task ★	Which components, entities and edges matter for this task?	Before starting work it can’t scope.
dependency_cone ★	What does this component pull in, transitively?	When judging extraction or upgrade cost.
changelog_architecture	What’s the architectural changelog between two analysed versions — significant entity flows between components, labelled by ref?	After parse + recover on two versions (four session IDs), e.g. summarizing what a release changed structurally.
init_spec ◆	Scaffold an architecture.spec.json from a layered, hexagonal, clean or mvc template.	Once, when a project has no spec yet.
propose_placement ◆	Which component does this new code belong in, and what may it depend on?	Before writing new code.
preview_impact ◆	Would a dependency from one component to another be allowed by the spec?	Before adding a cross-component import.
check_architecture ◆	Does the code still conform? PASS/WARN/FAIL, each violation with a fix.	After each change, until it passes.
remediate ◆	What are the ranked fixes, errors first, that restore conformance?	When a check fails.
get_full_result	What’s the untruncated data behind a summarized or budget-truncated response?	After a summary was cut down by max_tokens, when the detail is actually needed.
list_sessions	What session IDs do I already have open, and what type is each?	Before referencing a dep_graph/architecture argument in another call, or resuming mid-session.

★ The four task-shaped context tools each get a dedicated page with worked examples: see the sidebar or the links above.

◆ The five guardrail tools (v0.4.0) are documented together on the Architecture guardrail page, with the spec format and the arcade-guard CLI.

Token budgets

Every tool accepts an optional max_tokens argument, and responses that exceed it degrade rather than error. The MCP adapter picks one of two strategies depending on the response shape:

• Responses carrying a graph or architecture key (most pipeline tools) go through progressive, ordered reduction, stopping at the first level that fits the budget: return as-is if already within budget; cap each architecture component’s entity list to 10 (recording the original count as entities_truncated); collapse the graph’s entities map from full records to a bare FQN→kind mapping; drop the edges list in favor of an edge_summary relation-count dict; drop the entities map entirely, keeping only a kind-count entity_summary; reduce components to just name and num_entities; and finally drop the packages map, keeping only num_packages. A tight budget can mean losing entity or edge detail outright — this is per-level detail dropping, not smarter summarization.
• Everything else (session summaries, query/compare/explain results) goes through generic enforcement: it repeatedly finds and deletes the single largest top-level key — excluding the protected session_id, type, and _budget_truncated keys — until the payload fits or nothing droppable remains, and flags the result with _budget_truncated: true.

Either way, a truncated response still carries its session_id — call get_full_result to fetch the untruncated data behind it.

What this buys in practice

Measured with arcade-agent at the v0.4.0 development head, on five pinned repositories.

The question is how much it costs an agent to learn the shape of a codebase. The table counts tokens for four ways of getting that: reading every source file, fetching the full dependency graph plus recovered architecture, the same under max_tokens=8000, and one summarize call.

Repository	Entities	Read the source	Full graph + architecture	Same, max_tokens=8000	summarize
arcade-agent (Python)	490	144,707	80,372	7,283	1,201
click 8.1.7 (Python)	509	78,514	91,582	5,947	634
HikariCP 6.3.0 (Java)	557	68,046	98,126	196	1,019
disruptor 4.0.0 (Java)	373	54,940	72,126	7,104	1,041
caffeine 3.2.0 (Java)	785	155,290	148,286	155	839

Tokens are counted with tiktoken’s o200k_base BPE tokenizer, a real tokenizer rather than a character-count estimate. Claude’s own tokenizer, sampled on each payload kind, counted 1.09–1.25× as many tokens; the ratios between columns hold either way.

The headline is the outer pair: summarize costs 634–1,201 tokens, against 54,940–155,290 tokens to read the source of the same five repositories. Two caveats are visible in the table and matter as much as the headline:

• The full graph is not cheap. Graph plus architecture costs about as much as the source itself — less on two repositories, more on three. The savings come from summaries, session handles (the graph stays server-side) and budgets, not from the graph being smaller than code.
• Budgets are coarse. Reduction drops detail in ordered steps; when the step that keeps the entity map doesn’t fit, the next one drops it. That is why HikariCP and caffeine fall to under 200 tokens at an 8k budget instead of landing near it.

A summarize call is an orientation pass, not a substitute for reading the code an edit touches: it gives the package tree, dependency hotspots and entry points, from which the agent picks what to read. For a scoping question on arcade-agent itself (“add a Ruby language parser”), context_for_task returned a ranked 14-file slice in 5,113 tokens.

The full method, the pinned tags, and the reproduction command are in the methodology record, which also explains why the site’s earlier single-scenario “56% fewer tokens” figure was retired.

Reproduce this

The measurement script lives in the arcade-agent repository at docs/paper/icse2027-demo/measure_budget.py. From an arcade-agent checkout:

pip install "arcade-agent[languages]" tiktoken
python docs/paper/icse2027-demo/measure_budget.py --repos <dir-with-clones>

--repos holds shallow clones of the pinned repositories (click 8.1.7, HikariCP HikariCP-6.3.0, disruptor 4.0.0, caffeine v3.2.0); if one is missing, the script stops and prints the git clone command for it. --calibrate re-measures the Claude-tokenizer ratio through claude -p.