MCP tools reference

The installer registers an MCP server named cross-review with Claude Code and Codex. It exposes four tools that run one review: review_begin, review_wait, review_reply and review_end. The skills call them in that order. Each tool does the same work as the matching CLI verb.

Tool	Starts or continues	Returns
review_begin	A new session and its round 1.	session_dir, round, status, and analysis_prompt for peer skills.
review_wait	Waits for the current round to end (or for a time limit).	The round’s poll result plus next and next_reason.
review_reply	The next round, on the same reviewer thread.	status, session_dir, round, thread_id.
review_end	Finalizes the session and stops it.	status, session_dir, finalized, and verdict or error when present.

Every tool keeps its state on disk, so a review survives the MCP server exiting. Call review_wait again with the same session_dir to continue.

Note

Session state lives under .cross-review/sessions/ in the repository under review. See session files.

review_begin

Starts a session, renders round 1 from the skill’s template, and starts the reviewer in the background.

Parameter	Type	Required	Description
skill	enum	Yes	review-plan, review-impl, review-think or review-pr.
mode	string	For review-impl	working-tree or branch. Leave it out for the other skills.
input	string	Yes	Markdown with the placeholder values. Optional front matter holds NAME: value lines between --- lines. Each multi-line value is a ## NAME section, for example ## USER_REQUEST.
working_dir	string	Yes	Absolute path of the repository under review.
model	string	No	Reviewer model. When left out, the settings decide, and then the reviewer’s own default. It is kept for later rounds.
effort	string	No	Reasoning effort. When left out, the settings decide, and then high. It is kept for later rounds.
timeout_seconds	positive integer	No	Runner deadline for the reviewer. Default 18000 (5 hours).
reviewer	enum	No	Reviewer CLI. Only codex today. When left out, the settings decide.

Result, as JSON text:

{
  "session_dir": "/path/to/repo/.cross-review/sessions/review-impl-20261016-001",
  "round": 1,
  "status": "running"
}

• analysis_prompt is present for the peer skills (review-think, review-pr). The orchestrator writes its own analysis from it before it compares.
• dashboard_url is present when the dashboard follows reviews (open_dashboard). dashboard_error replaces it when the dashboard could not open the session. The review runs either way.

review_wait

Waits up to max_wait_seconds for the reviewer. It returns early when the round ends.

Parameter	Type	Required	Description
session_dir	string	Yes	The session_dir that review_begin returned.
max_wait_seconds	integer, 0 or more	No	How long this call waits. The default comes from the server’s REVIEW_WAIT_DEFAULT_S environment variable. The installer sets it to 270; without it the default is 50.

The result has the poll fields of the round and two more:

Field	Meaning
status	running, completed, failed, stalled or timeout. running also comes back when max_wait_seconds runs out first.
round	The round number.
elapsed_seconds	Seconds since the round started.
thread_id	The reviewer thread, once known.
review	The parsed review when the round completed: verdict, and the blocks (issues).
activities	What the reviewer did since the last call.
error, failure_reason, timeout_reason, recoverable, progress_observed	Present on a failed, stalled or timed-out round.
next	What the orchestrator does next. See the table below.
next_reason	Why. See the table below.

next values

next	What the orchestrator does
running	Calls review_wait again. next_reason is reviewer_running.
respond	Fixes the valid findings and rebuts the others, then calls review_reply. Plan and implementation reviews only. next_reason is open_issues, or verdict_ followed by the verdict in lower case.
cross_check	Peer skills only. Compares the findings with its own analysis, then calls review_reply, or review_end with an outcome. next_reason is peer_verdict_is_advisory.
done	Calls review_end. next_reason is approved (plan and implementation reviews), or stalemate.
ask_user	Asks the user what to do. next_reason is missing_verdict: the round ended with neither a verdict nor findings.
stopped	The round ended without a usable review. next_reason is recoverable_timeout when the runner deadline passed after progress and the thread can be resumed. Otherwise it is the failure reason, such as stalled, turn_failed or reviewer_process_exit.

Note

A plan or implementation review ends when the verdict is APPROVE. A peer skill’s round ends with an advisory status (CONTINUE, CONSENSUS or STALEMATE) that never ends the session by itself. The orchestrator ends it with review_end and an outcome.

review_reply

Sends the next round. The skill’s round 2+ template is filled from input and sent to the same reviewer thread.

Parameter	Type	Required	Description
session_dir	string	Yes	The session.
input	string	Yes	The next round’s placeholder values, in the same format as review_begin.
model	string	No	Changes the stored model for later rounds.
effort	string	No	Changes the stored effort for later rounds.

When model and effort are left out, the stored values are used. The sandbox is always the one stored in the session.

Result: status (started), session_dir, round (the new round number), and thread_id.

review_end

Finalizes the session when it can, then stops the reviewer.

Parameter	Type	Required	Description
session_dir	string	Yes	The session.
outcome	consensus or stalemate	No	Required for peer skills whose exit rule is met. Plan and implementation reviews take the verdict from the last round.

Result: status (ended), session_dir, finalized (true when meta.json was written), and verdict when it was set.

• A plan or implementation review is finalized only when its last round reached done. A peer review is finalized only with an outcome. Otherwise the call just stops the session and returns finalized: false; this is a normal result, not an error.
• When finalizing was tried and failed, the session is still stopped, and the result also has an error field and isError set.

Errors

A failed call returns the text {"error": ..., "code": ...} with isError set to true. The most common codes:

Code	Meaning
CONFIG_INVALID	A settings file is broken. No session is created. Fix the file named in the message.
INVALID_INPUT	A parameter is missing or wrong, for example a review-impl call without mode.
UNKNOWN_SKILL	The skill is not one of the four review skills.
REVIEWER_NOT_FOUND	The codex CLI is not in PATH.
INVALID_SESSION	session_dir does not hold a readable session.
ROUND_STILL_RUNNING	review_reply was called while the round is still running. Call review_wait first.

Other codes come from the runner and are passed through unchanged.