MCP tools reference

astria mcp runs an MCP stdio server (newline-delimited JSON-RPC 2.0, protocol 2025-06-18, server name astria). Any MCP-capable agent — Claude Code, Codex, Cursor, … — can point at it and query the graph without shelling out to the CLI.

Point your agent's MCP config at it:

{
  "mcpServers": {
    "astria": {
      "command": "astria",
      "args": ["mcp"]
    }
  }
}

The server's own instructions tell agents the intended flow: orient with repo_map first, ask natural-language questions with query_graph, drill into symbols with explain/get_neighbors, trace connections with shortest_path, and check affected before changing a node.

Tools

query_graph

BFS/DFS traversal of the knowledge graph for a natural-language question. Returns a compact subgraph context.

Argument	Type	Default	Notes
question	string	—	required
mode	bfs | dfs	bfs
depth	integer	2	Maximum traversal depth
budget	integer	2000	Maximum query text tokens (o200k_base), including header and continuation metadata; excludes the MCP JSON envelope
directed	boolean	false	Follow edges only in stored direction (caller → callee, importer → module)
detail	all | high	all	high keeps only EXTRACTED and DECLARED facts, regardless of numeric popularity scores
cursor	integer	0	Continuation token from a previous truncated result

CLI and MCP use the same query engine, including optional embedding recall when compiled with the embed feature and both node embeddings and a cached model are available. Queries never download a model. Each operation reloads a consistent SQLite graph snapshot, so long-running MCP sessions see subsequent database updates.

Undirected traversal can cross an edge backwards, but returned arrows always retain the stored source and target and the exact relationship traversed.

Truncated results report the next cursor value — re-run with cursor set to fetch the next slice of node and edge records. CLI and MCP use the same budgeted query text; transport wrappers do not append an extra summary.

repo_map

Aider-style repo map: files ranked by PageRank over the reference graph, with top symbols per file. One budgeted blob to orient on a codebase.

Argument	Type	Default	Notes
budget	integer	2000
detail	all | high	all

explain

Explain a node: its metadata and up to 20 neighbors with relations and confidence. Errors with node not found for unknown labels.

Argument	Type	Notes
node	string	required — node label

get_neighbors

List a node's neighbors, optionally filtered by relation.

Argument	Type	Notes
node	string	required
relation	string	e.g. Calls, Imports, Uses

shortest_path

Shortest path between two nodes, with the relation of each hop.

Argument	Type	Default	Notes
source	string	—	required
target	string	—	required
directed	boolean	false
detail	all | high	all

affected

Blast radius: everything impacted by changing a node — reverse reachability over calls/imports/uses.

Argument	Type	Default	Notes
node	string	—	required
depth	integer	2
relation	string	—	Filter to one relation type

god_nodes

The highest-degree nodes — what everything connects through. No arguments.

list_communities

All communities with their hub-based labels, sizes, and cohesion. No arguments.

graph_stats

Node/edge/community/file counts for the graph. No arguments. If it reports 0 nodes, the graph has not been built yet — run astria run <path> first.

health

Code-health report with unreachable-symbol candidates, circular file dependencies, hub concentration, and graph staleness. Returns a heuristic score from 0 to 100. No arguments.

Example session

{"jsonrpc": "2.0", "id": 1, "method": "tools/call",
 "params": {"name": "query_graph",
            "arguments": {"question": "where does auth live?", "budget": 1500}}}

NODE  authenticate_user  src/auth/auth.rs:45
NODE  AuthMiddleware     src/auth/middleware.rs:12
EDGE  AuthMiddleware ─CALLS→ authenticate_user  EXTRACTED · 0.97  @middleware.rs:28

(2 nodes, 1 edge)

Every EDGE line carries its provenance (@file:line) and confidence class, and node lines carry src=file:line — see CLI reference → Query flags for the same output shape from the command line.

Fidelity tiers

All traversal tools accept detail: "high" to keep only declared facts (EXTRACTED, strength ≥ 0.9) and drop everything inferred — including learned edges and similar_to embeddings. Use it when an answer must be defensible; use the default all for recall.