// docs · v1.x

MCP server — agent review gate

commitbrief mcp runs a Model Context Protocol server over stdio so an AI agent or host can call CommitBrief as a self-review gate before it submits code. One review tool, the same pipeline as commitbrief --json, structured findings back.

commitbrief mcp runs a Model Context Protocol server over stdio so an AI agent or host — Claude Desktop, an agent runtime, an MCP-aware IDE — can call CommitBrief as a tool. The typical use is a self-review gate an agent runs on its own diff before it submits code. New in v1.9.0 (ADR-0028).

It speaks JSON-RPC 2.0 over the MCP stdio transport, is stdlib-only (no MCP SDK, no new dependency), and is fully opt-in: it changes nothing about the existing commands.

The one tool: `review`

The server exposes a single tool, review, which runs the exact same review pipeline as commitbrief --json — diff acquisition, filtering, the pre-send guard and secret scanner, the cost preflight, the cache, the flaky-test pre-pass, and signal control — and returns the structured findings (JSON schema v1) plus a short text summary. It does not re-implement the review; it reuses the same runReview path a terminal review takes, so there is zero behavioral drift.

Tool arguments

All arguments are optional:

Argument	Type	Meaning
`staged`	bool	review the staged diff (default)
`unstaged`	bool	review the working tree (mutually exclusive with `staged`)
`diff`	string[]	`git diff` range args, e.g. `["HEAD~3","HEAD"]` or `["main...feature"]`
`provider`	string	override the configured provider
`model`	string	override the configured model
`fail_on`	string	`critical \| high \| medium \| low \| info \| any \| none` — reported as a gate failure in the summary; findings are still returned
`min_severity`	string	hide findings below this severity in the returned set
`no_flaky`	bool	skip the deterministic flaky-test detector
`file`	string[]	review only these files — exact path or gitignore-style glob
`dir`	string[]	review only files under these directories or dir globs
`exclude_file`	string[]	skip these files/globs; same rules as `file`, applied after it so an exclusion wins
`exclude_dir`	string[]	skip these directories/globs; applied after `dir`
`author`	string[]	review only commits by these authors (name or email, case-insensitive)
`committer`	string[]	review only commits committed by these people
`start_date`	string	`YYYY-MM-DD`, inclusive
`end_date`	string	`YYYY-MM-DD`, inclusive
`text`	string	commit message text, plus commits unique to a branch whose name contains it
`max_commits`	int	cap the commit selection (`0` = the built-in default of 200)
`merges`	bool	include merge commits (excluded by default)

The path and commit filters landed on the tool in v1.15.0. The path pair was previously CLI-only in practice: the MCP seam resets the global flag state, so a host had no way to narrow a review by path at all. Any of the commit filters switches the scope to a history walk, which makes staged / unstaged invalid for that call — see Commit filters.

The result carries two content blocks: a one-line summary (finding counts, provider, and a GATE FAILED note when fail_on trips) and the schema-v1 JSON document.

Sandbox-rerun never runs here

If a repo configures review.sandbox_command, the MCP path still won’t execute it — unconditionally, with no toggle. An agent host must not run repository code unattended, so flaky findings returned over MCP stay at the static-only confidence level. See Flaky-test detector.

Errors vs. gate failures

A fail_on gate is reported in the summary — the findings still come back, so the agent can read them. A genuine failure — no repo or changes, a provider error, an aborted secret-scan guard — comes back as an MCP tool error instead.

Wiring it into a host

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

The host launches the process, performs the initialize handshake, discovers the review tool via tools/list, and calls it via tools/call. The server reads requests on stdin and writes responses on stdout until the host closes the stream; diagnostics go to stderr.

A self-review gate for coding agents

The intended pattern: an agent finishes a change, calls review on its own diff, and reads the findings before it opens a PR or hands the work back. Pair it with the policy gate — commitbrief guard --from-json can consume the very JSON the review tool returns, so the agent’s self-review and your merge gate share one contract and one definition of “passes.”

The one tool: review