MCP tools reference

Status: pixmoat mcp needs the pixmoat CLI, which has no public install path yet. This reference is generated from the CLI source and lists the tools it will expose.

pixmoat mcp exposes 11 tools over stdio. It authenticates with the same PIXMOAT_URL, PIXMOAT_TOKEN and PIXMOAT_PROJECT environment variables as the CLI.

approve_runs

Approve one or more runs in a build. Accepts handles (e.g. “h7k2”) or UUIDs in run_ids, or change group IDs (e.g. [“g1”]) in group_ids. Sends decisions with source=agent for audit trail. Only approve when the visual change was intended. Respects the project’s agent_auto_approve setting.

check_build

Check a pixmoat build for visual regressions. Returns a compact text digest (default) with a single-word verdict on line 2 and one line per changed screenshot. Waits for diffing to complete by default.

Verdicts: PASS (exit 0, all clean), REVIEW (exit 1, diffs pending), REVIEW_NEW (exit 2, new snapshots only), FAIL (exit 3, rejected or failed), WAIT (diffing in progress, only with wait: false).

Each run line shows: <handle> <name> <viewport> <browser> <ratio%> <severity> <regions>. Handles are 4-char short IDs usable in approve_runs, reject_run, and get_screenshot. A ! continuation line means a human rejected this screenshot — read the comment.

Decision rules: flaky/quarantined = skip; ! line = fix what the human flagged; unintended diff = regression, fix the code; intended diff = approve. Pass format: “json” for the full JSON response.

finish_review

Capability: finish_review. Finish a staged agent review after inspecting every actionable run and submitting an approve_runs or reject_run decision for each one. This is the final explicit step: it never decides runs automatically and cannot be forced. Pixmoat enforces the project’s agent and human approval policy.

get_build_context

Read build provenance, completeness, quality audit counts, and review policy. Use alongside check_build before deciding. Missing viewports, browsers, or unevaluated audits do not mean the build passed.

get_feedback

Show recent rejection comments for a snapshot key. If a snapshot was previously rejected by a human, read the feedback to understand what needs fixing before re-submitting.

get_history

Show recent change history for a snapshot key. Check before deciding on a diff to see if this screenshot has been changing frequently or was recently rejected.

get_run_details

Read evidence for one screenshot: changed regions, ignore regions, decision and comment, accessibility violations and DOM selectors, performance metrics and baseline, console failures, and agent review policy. Missing audits are explicitly marked evaluated=false. Use get_screenshot for visual evidence and get_feedback for earlier human rejection comments. Visual approval does not resolve separate quality findings.

get_screenshot

Returns a cropped side-by-side triptych image (baseline | current | diff, left to right, separated by blue/green/magenta bars) around the largest changed region. Use after check_build to visually inspect diffs before approving or rejecting.

Pass region: “all” when region_count > 1 to see all changed areas. Pass region: “full” to see the whole page. For new screenshots (no baseline), the triptych shows only the current pane.

Accepts run handles (e.g. “h7k2”) or UUIDs in run_ref.

list_builds

List recent builds for the project. Returns build IDs, branches, commit SHAs, and statuses. Use to find the build ID after a capture, or to check the status of builds on a branch.

list_projects

List organizations and projects accessible to the current token. Requires a personal access token (PAT). Returns orgs and their projects with agent_auto_approve settings.

No parameters.

reject_run

Reject a run in a build with a comment explaining what is wrong. Accepts a handle (e.g. “h7k2”) or UUID in run_id. A comment is required. Reject when the visual change is a regression that you cannot fix.