MCP server

MCP server (commitbrief mcp)

commitbrief mcp runs a Model Context Protocol server over stdio so an AI agent or host can invoke CommitBrief as a tool — typically a self-review gate the agent runs before it submits code. It speaks JSON-RPC 2.0 over the MCP stdio transport, is implemented with the Go standard library only (no MCP SDK, no extra dependency), and is fully opt-in: enabling it changes nothing about the other commands.

Note

The server exposes the same review pipeline as commitbrief --json — diff acquisition, the three-layer filtering, the pre-send guard and secret scanner, the cost preflight, the response cache, the flaky-test pre-pass, and signal control all run exactly as they do for a terminal review. The MCP path reuses the review code rather than re-implementing it.

What it exposes

A single tool, review, that reviews the current repository's diff and returns the structured findings (JSON schema v1) plus a short text summary.

Tool: review

All arguments are optional. With no arguments it reviews the staged diff (commitbrief --staged).

Argument	Type	Default	Meaning
staged	boolean	true	review the staged diff
unstaged	boolean	false	review the working-tree diff instead (mutually exclusive with staged)
diff	string[]	—	git diff arguments for a range review, e.g. ["HEAD~3","HEAD"] or ["main...feature"]; forwarded verbatim to git
provider	string	configured	override the provider for this review
model	string	configured	override the model for this review
fail_on	string	—	critical | high | medium | low | info | any | none — report a gate failure when a finding meets/exceeds this severity. Findings are still returned.
min_severity	string	—	critical | high | medium | low | info | none — hide findings below this severity in the returned set (the gate still sees the full set)
no_flaky	boolean	false	skip the deterministic flaky-test detector
file	string[]	—	review only these files; exact path, or a gitignore-style glob when the value contains */?/[
dir	string[]	—	review only files under these directories (or matching dir globs)
exclude_file	string[]	—	skip these files or globs; applied after file, so an exclusion wins
exclude_dir	string[]	—	skip files under these directories or matching dir globs
author	string[]	—	review only commits by these authors — case-insensitive substring of the name or the email; multiple values are OR'd
committer	string[]	—	same, on the committer identity
start_date	string	—	YYYY-MM-DD; commits with author date on or after this day, inclusive
end_date	string	—	YYYY-MM-DD; commits with author date on or before this day, inclusive
text	string	—	commits whose message contains this text, plus commits unique to a branch whose name contains it
max_commits	integer	0 (⇒ 200)	cap the commit selection
merges	boolean	false	keep merge commits, which are excluded by default

The path and commit filters are new in v1.15.0. Before that the file/dir narrowing was unreachable over MCP at all: the reuse seam resets the CLI's global flag state, so there was no channel for it.

Setting any of author / committer / start_date / end_date / text switches the scope to a commit walk — the returned diff is the concatenation of the matching commits' patches, and staged / unstaged do not apply (the handler leaves the scope unset for you). The returned document carries meta.filtered_commits so the host can see how many commits went in. Different filter kinds are AND'd, multiple values of one kind are OR'd. See Filtering.

Unknown arguments are a tool error, not a silent no-op — the schema is additionalProperties: false and decoding rejects unknown fields, so a typo like failon surfaces immediately.

The tool result has two content blocks:

1. A text summary — finding counts by severity, the provider/model used, whether the response was cached, and a GATE FAILED: … note when fail_on tripped.
2. The JSON schema-v1 document — the same bytes commitbrief --json emits.

A genuine failure (no git repo, no changes to review, a provider error, or an aborted secret-scan guard) is returned as an MCP tool error (isError: true) carrying the message, so the agent can react. The fail_on gate is not a tool error — the findings are valid and returned; the gate is reported in the summary.

Wiring it into a host

Register commitbrief mcp as a stdio MCP server in your host's configuration.

Claude Desktop / generic MCP host

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

If commitbrief is not on the host's PATH, use an absolute path for command (e.g. /usr/local/bin/commitbrief). Provider credentials are resolved the same way as for any review — from ~/.commitbrief/config.yml, the repo config, or environment variables (see Configuration files and Environment variables). Run commitbrief setup once first so the server has a working provider.

The host launches the process, performs the initialize handshake, discovers the review tool via tools/list, and invokes it via tools/call. The process reads JSON-RPC requests on stdin and writes responses on stdout until the host closes the stream; human-readable diagnostics go to stderr and never pollute the JSON-RPC channel.

Protocol

• Transport: line-delimited JSON over stdio — one JSON-RPC 2.0 message per line. (The optional Content-Length header framing is not used; the newline form is the stdio default.)
• Protocol version: 2024-11-05.
• Methods: initialize, tools/list, tools/call, ping. Notifications (id-less requests, e.g. notifications/initialized) are accepted and not answered.

Worked example (raw JSON-RPC)

Requests the host sends (one per line), and the responses the server returns:

// → initialize
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{}}}
// ← {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{}},"serverInfo":{"name":"commitbrief","version":"…"}}}

// → notifications/initialized   (no response)
{"jsonrpc":"2.0","method":"notifications/initialized"}

// → tools/list
{"jsonrpc":"2.0","id":2,"method":"tools/list"}
// ← {"jsonrpc":"2.0","id":2,"result":{"tools":[{"name":"review","description":"…","inputSchema":{ "type":"object", … }}]}}

// → tools/call review (staged diff)
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"review","arguments":{"staged":true}}}
// ← {"jsonrpc":"2.0","id":3,"result":{"content":[
//      {"type":"text","text":"CommitBrief review: 1 finding(s) (1 info). Provider: anthropic/…."},
//      {"type":"text","text":"{\"schema\":1,\"content\":\"\",\"findings\":[…],\"summary\":{},\"meta\":{…}}"}
//    ]}}

Sandbox-rerun is suppressed

If you've configured review.sandbox_rerun and review.sandbox_command (see Review: sandbox-rerun confirmation), be aware that it never runs through the MCP review tool — unconditionally, regardless of flag or config, with no override. The flaky detector still runs and its findings are still returned; only the empirical rerun confirmation is skipped, so a flagged test stays at the static-only confidence level through this path even though a terminal commitbrief review with the same config would confirm it. This is not a bug to work around: an agent host must not execute repository code unattended, so mcp (and guard, which shares the same seam) deliberately never binds the runner. See ADR-0033 §6 for the full rationale.

Notes and limits

• One review at a time. The server is single-connection and processes requests sequentially — a review is a blocking operation and there is exactly one host on the other end of stdio.
• Guards still apply. Because the agent host is non-interactive, a triggered secret-scan or cost preflight aborts (rather than auto-approving) and the abort is surfaced as a tool error — a review that would prompt a human is never silently approved for an agent.
• Config is re-read per call, so editing ~/.commitbrief/config.yml between calls takes effect without restarting the server.
• --timeout is a per-tool-call budget here, not a lifetime for the server — a long-lived stdio server must never carry a deadline. Both commitbrief mcp --timeout 10m and review.timeout: "10m" bound each review call individually. See Global flags.

See also

• JSON schema v1 — the exact shape of the returned findings.
• Review (default command) — the pipeline the tool reuses.
• Configuration files · Environment variables — how the provider/credentials resolve.
• --fail-on and exit codes — the gate semantics fail_on mirrors.