# 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 docs · v1.x · Operations

Canonical URL: https://commitbrief.com/docs/1.x/mcp-server

---

`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](/docs/1.x/flaky-tests), and
[signal control](/docs/1.x/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](/docs/1.x/review-scopes#commit-filters-v1150).

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](/docs/1.x/flaky-tests#never-in-an-agent-context).

### 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:

```json
{
  "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](/docs/1.x/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](/docs/1.x/policy-gate) — gate the review JSON an
  agent produces, with no second provider call.
- [Output formats](/docs/1.x/output-formats) — the JSON schema v1 the
  `review` tool returns.
- [Safety and cost](/docs/1.x/safety-and-cost) — the pre-send guard and
  secret scan the MCP path still runs.
- [Severity and CI gating](/docs/1.x/severity) — what `fail_on` means.