MCP Tools
ArchGraph exposes 21 tools via the Model Context Protocol. Every tool is a POST on the MCP endpoint (https://mcp.archgraph.dev/mcp) carrying an Authorization: Bearer ag_… header. Request/response bodies are JSON.
Plan tiers
| Tier | Tools available |
|---|---|
| Free | 8 core code-intelligence tools |
| Pro | All 21 tools (Free + 13 Pro) |
| Enterprise | Self-hosted deployment with all 21 tools + audit log + SSO |
If your plan does not cover a tool, the gateway returns a 403 with a tier hint.
Free tier (8)
search
Search code across repositories with rich query syntax. Use when an agent needs to locate a symbol, enumerate files of a type, or run repo:/lang:/file:/type: filters.
| Parameter | Type | Description |
|---|---|---|
query | string | Rich query string (e.g. lang:python type:function validate) |
name | string | Symbol name pattern (legacy; prefer query) |
type | string | Node type: function, class, struct, interface, enum, module, file |
file_pattern | string | File path pattern |
limit | number | Max results (default 20) |
workspace_id | string | Workspace ID for cross-repo search (Pro) |
{ "query": "lang:python type:function validate", "limit": 10 }
stats
Graph-level node counts by type for the active repo (or workspace).
| Parameter | Type | Description |
|---|---|---|
workspace_id | string | Optional — workspace-scoped stats |
{ "nodes": 12843, "by_type": { "function": 7120, "class": 842, "file": 1231 } }
impact
Blast radius — trace upstream callers and downstream callees for a symbol.
| Parameter | Type | Description |
|---|---|---|
symbol_id | string | Symbol identifier (e.g. func:src/auth.py:validate:42) |
direction | string | upstream, downstream, or both |
max_depth | number | Max traversal depth (default 5) |
workspace_id | string | Optional — cross-repo impact (Pro) |
context
360° view of a symbol — callers, callees, file, security flags, surrounding nodes.
| Parameter | Type | Description |
|---|---|---|
symbol_id | string | Symbol identifier |
workspace_id | string | Optional — cross-repo context (Pro) |
source
Source code body for a symbol.
| Parameter | Type | Description |
|---|---|---|
symbol_id | string | Symbol identifier |
workspace_id | string | Optional — cross-repo source lookup (Pro) |
search_calls
Search function call relationships (CALLS edges).
| Parameter | Type | Description |
|---|---|---|
caller | string | Caller name pattern |
target | string | Target/callee name pattern |
file | string | File path filter |
resolved_only | boolean | Only return resolved edges |
max_depth | number | Max chain depth (default 1) |
limit | number | Max results (default 20) |
workspace_id | string | Optional — cross-repo (Pro) |
detect_changes
Recently changed files with downstream impact.
| Parameter | Type | Description |
|---|---|---|
since | string | Time window (e.g. 7d, 30d) |
import_tree
Module-level import/dependency graph; detects circular imports.
| Parameter | Type | Description |
|---|---|---|
module | string | Optional — start from a specific module |
Pro tier (13)
query
Execute read-only Cypher queries against the code graph. Writes are blocked at the engine level.
| Parameter | Type | Description |
|---|---|---|
cypher | string | Cypher query (MATCH ... RETURN ...) |
{ "cypher": "MATCH (f:Function) WHERE f.name CONTAINS 'auth' RETURN f.name, f.file LIMIT 5" }
find_vulnerabilities
CVE/GHSA matches on the dependencies extracted from the repo.
| Parameter | Type | Description |
|---|---|---|
severity | string | Filter by critical, high, medium, low |
taint_paths
Taint propagation source→sink chains. Backed by the Joern CPG taint engine for high-confidence findings.
| Parameter | Type | Description |
|---|---|---|
source_type | string | Filter source category (http_input, file_read, env_var) |
sink_type | string | Filter sink category (sql_query, command_exec, file_write) |
max_depth | number | Max chain length (default 10) |
workspace_id | string | Optional — cross-repo |
data_flow
Track data flow through assignments, parameter passing, and return values.
| Parameter | Type | Description |
|---|---|---|
symbol_id | string | Function or variable node ID |
direction | string | forward, backward, or both |
max_depth | number | Max depth (default 5) |
workspace_id | string | Optional — cross-repo |
clusters
Functional clusters (Leiden community detection) with cohesion and coupling scores.
| Parameter | Type | Description |
|---|---|---|
min_size | number | Minimum cluster size to include |
churn
File modification hotspots from git history. Surfaces the top-N most-edited files and pairs them with structural complexity.
| Parameter | Type | Description |
|---|---|---|
since | string | Time window for churn (e.g. 90d) |
top | number | Number of hotspots (default 20) |
cfg
Control flow graph for a function — basic blocks and branch edges.
| Parameter | Type | Description |
|---|---|---|
symbol_id | string | Function symbol ID |
processes
Execution flow traces from entry points (CLI mains, HTTP handlers, cron jobs) through their call chains.
| Parameter | Type | Description |
|---|---|---|
entry_type | string | Filter by cli, http, cron, etc. |
diff_summary
Compare the current state of the repo against the stored graph — surfaces drift, deleted files, and new symbols.
| Parameter | Type | Description |
|---|---|---|
against | string | Comparison target (stored, branch:main) |
workspaces
List workspaces — repo groups used for cross-repo analysis. Returns id, name, description, and repo_count. Pass the returned id to cross_repo_impact, cross_repo_taint, or dependency_graph.
[
{ "id": "ws_…", "name": "Production Backend", "description": "Auth + billing services", "repo_count": 5 }
]
cross_repo_impact
Cross-repository blast radius. Shows which functions in OTHER repos in the workspace are affected when you change a symbol.
| Parameter | Type | Description |
|---|---|---|
symbol_id | string | Symbol identifier |
direction | string | upstream, downstream, or both |
max_depth | number | Max traversal depth (default 5) |
workspace_id | string | Workspace whose repos define the cross-repo scope |
cross_repo_taint
Cross-repository taint flow. Tracks data from input sources in one repo to dangerous sinks in another.
| Parameter | Type | Description |
|---|---|---|
workspace_id | string | Workspace defining the cross-repo scope |
dependency_graph
Repo-level dependency graph for a workspace — which repos depend on which, with edge weights.
| Parameter | Type | Description |
|---|---|---|
workspace_id | string | Workspace ID |
{
"nodes": [{ "repo_tenant_id": "tenant_…__auth-service" }],
"edges": [{ "source": "…__auth-service", "target": "…__shared-libs", "type": "DEPENDS_ON_REPO", "weight": 12 }],
"truncated": false,
"total_available": 7
}
Session helpers
In addition to the 21 tools above, the gateway provides two session helpers (no plan gate):
repos— list all repositories your account has access touse_repo— set the active repository for the current session; subsequent tools scope to it