MCP Server
Run xgrep as a Model Context Protocol server for AI agents — the full tool list, inputs, and how it differs from the CLI.
MCP Server
Run xgrep as an MCP server so an AI agent can scan for vulnerabilities and navigate a codebase through structured tool calls:
xgrep mcp # serve over stdio
xgrep mcp -f rules/ # preload a rule set for the scan tool (see below)The server speaks MCP over stdio — point any MCP-capable client (Claude Code,
editor agents, your own harness) at the xgrep mcp process. For how agents
combine these tools in practice — scan, trace dataflow, triage a finding — see
AI agents.
Tools
The server exposes one scanning tool, the code-graph tools, the
code-intelligence (inspect) tools, and the autofix verify/apply tools. All are
read-only except fix_apply and fix_changeset_apply, which write the accepted
fix to disk atomically (gated by the same harness as their *_verify
counterparts, so a rejected fix is never written). Use the *_verify tools for a
read-only check.
Scanning
| Tool | Inputs | Description |
|---|---|---|
scan | path (required), rules, language | Run xgrep rules against a local file or directory and return findings as JSON. |
scan inputs:
path— a local file or directory. A directory is scanned recursively. (Unlike the CLI, the scan tool does not accept remote-repo URLs or stdin — see Differences from the CLI.)rules— path to a rule file or directory. Optional: when omitted (and the server wasn't started with-f/--rules), the scan tool falls back to the built-in corpus filtered tosecurity+secrets— the same out-of-the-box default as the CLI — so an agent can scan without configuring rules first.language— force a language (e.g.go,python,javascript) instead of detecting it from the file extension.
Code graph
Build and query the call graph. The graph is built on first use and cached in memory for the life of the server process.
| Tool | Inputs | Description |
|---|---|---|
graph_build | path | Build or refresh the code graph for a directory. |
graph_callers | name | Find all callers of a function. |
graph_callees | name | Find all functions called by a function. |
graph_paths | source, target | Find call paths between two functions. |
graph_context | name, depth | N-hop call neighborhood with inlined source, for understanding code flow. |
graph_reachable | name | All functions transitively reachable from a function via call edges. |
name matches a function by partial name or a full ID like
pkg/file.go::FuncName.
Code intelligence
The same capabilities as xgrep inspect,
exposed as tools. The code graph and search index are built on first use and
cached in .xgrep/.
| Tool | CLI equivalent | Description |
|---|---|---|
codebase_overview | inspect overview | Languages, packages, entry points, key types. Run this first in an unfamiliar codebase. |
symbol_search | inspect symbol | Find a symbol by name (exact, prefix, or substring) with its location. |
text_search | inspect search | Fast trigram-indexed text search (substring or regex, with language/file filters). |
go_to_definition | inspect definition | Find the definition of the symbol at a file:line:col position. |
hover | inspect hover | Documentation, type info, and parameters for the symbol at a position. |
get_ranges | inspect ranges | All symbols in a line range of a file, with docs and type info. |
find_references | inspect references | All usages of a symbol: callers, callees, and reference edges. |
find_implementations | inspect implementations | All types implementing an interface. |
file_symbols | inspect outline | Outline of a file — every symbol, sorted by line. |
impact_analysis | inspect impact | Blast radius of changing a symbol: callers, affected files, risk score. |
dependency_graph | inspect deps | Upstream/downstream call dependencies, transitively. |
Autofix (agent round-trip)
The write-capable half of the autofix loop: an agent reads an
assisted finding's fix contract (scan → extra.fix_info.contract), authors a
candidate edit, and submits it here. xgrep runs it through the parse-clean +
re-scan harness and returns a verdict — accepted, or a machine-readable
rejection reason to iterate on — plus a unified-diff preview.
| Tool | CLI equivalent | Description |
|---|---|---|
fix_verify | xgrep fix verify | Verify a candidate (path, rule_id, edits) without writing. Read-only. |
fix_apply | xgrep fix apply | Verify and write the accepted fix atomically. A write-capable tool — use fix_verify for a read-only check. |
fix_changeset_verify | xgrep fix verify (changeset) | Verify a cross-file changeset ({rule_id, files:[{path,edits}]}) as one all-or-nothing unit, without writing. |
fix_changeset_apply | xgrep fix apply (changeset) | Verify a cross-file changeset and write every file atomically, only if the whole set passes. Write-capable. |
Differences from the CLI
The MCP scan tool is a deliberately narrow surface for agents — it is not a
full mirror of the CLI scan:
CLI xgrep scan | MCP scan tool | |
|---|---|---|
| Local file / directory | Yes | Yes |
| Multiple targets | Yes | One path |
| Remote git repo (URL/shorthand) | Yes | No |
| stdin / stdin manifest | Yes (--stdin, --stdin-files) | No |
| Built-in rule corpus by default | Yes (security,secrets) | Yes (security,secrets) |
--category / --subcategory / --severity filters | Yes | No (built-in fallback is fixed to security,secrets) |
--include / --exclude globs | Yes | No |
For scans that need remote repositories, stdin, or category/severity filtering,
drive the CLI directly. The graph and inspect tools, by contrast, are a complete
mirror of their
inspect and
graph commands.