MCP server — agent review gate

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

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.

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

Register commitbrief mcp as a stdio MCP server. For a Claude Desktop-style host config:

{
  "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.”

See also

• Policy gate — guard — gate the review JSON an agent produces, with no second provider call.
• Output formats — the JSON schema v1 the review tool returns.
• Safety and cost — the pre-send guard and secret scan the MCP path still runs.
• Severity and CI gating — what fail_on means.