UI Verify MCP server: tool reference
The UI Verify MCP server lets a coding agent list builds, read diffs, see the pixels, comment, and accept baselines, after one browser login.
One connection reaches every project in every team you are a member of. This page lists each tool with its key arguments and what it returns. To add the server to Claude Code, Cursor, Codex, or another client, see UI Verify MCP server for coding agents; for the review workflow itself, see Triage visual changes from your coding agent.
What is the UI Verify MCP endpoint?
The UI Verify MCP endpoint is https://uiverify.ai/mcp. It uses the Streamable HTTP transport and is stateless: each call stands on its own, with no session to keep alive. SSE is not offered.
How do I log in to the UI Verify MCP server?
The UI Verify MCP server uses OAuth: you log in once with your UI Verify account in the browser, and the client keeps the login and renews it on its own, so you do not log in again every session. The client config holds only the endpoint URL and no secret. In Claude Code, Cursor, VS Code, and Gemini CLI it lives in a project file (.mcp.json, .cursor/mcp.json, .vscode/mcp.json, .gemini/settings.json) you can commit, so the whole team gets it and every teammate logs in with their own account. Codex keeps it in each person's own config, so each teammate runs the one codex mcp add command. The setup for Claude Code, Cursor, Codex, Gemini CLI, and other clients is in UI Verify MCP server for coding agents.
Choosing a project: list_projects and projectId
list_projects lists every project you can access, with its projectId, team, name, type, repository, and last build time. Most calls never need it: a call that takes a buildId, diffResultId, or commentId already knows its project. A call that looks a build up by commitSha or prNumber, and list_builds, takes an optional projectId. If you can access a single project it is used automatically; if you can access several, the call returns an error that lists them, so the agent can pass the right projectId and retry.
Access follows your team membership and is checked on every call: a project in a team you are not in reads as not found, and leaving a team ends access on the next call. Reviews an agent makes this way are recorded as the agent acting for you.
What does the MCP server show before I have a project?
If you log in before you are in any project, list_projects shows the UI Verify demo project, marked demo: true, so your agent can show you a real build and its before and after diff right away. To see it, ask your agent to "show me the UI Verify demo". You can also open the demo build in your browser. Every read tool works on it, and each response carries a note saying it is the demo. Nothing can be accepted, ignored, or commented on there, and its review comments stay private to its team. Once you create a project or accept a teammate's invite, your own projects replace the demo.
Build selector: commitSha, prNumber, or buildId
A build selector is how most tools choose the build to act on. Pass exactly one of the three fields; passing none or more than one returns an error. With commitSha or prNumber you can also pass projectId to say which project to look in.
| Field | Resolves to |
|---|---|
commitSha | The latest build for that git commit |
prNumber | The latest build for that pull request number |
buildId | That exact build |
commitSha and prNumber skip preview builds from uiverify check; reach one by its buildId. list_builds takes no selector, since it is how you find a build. Tools that act on one story or one comment take that item's id instead: diffResultId for review_diff, and commentId for update_comment, resolve_comment, and delete_comment.
Pagination and page sizes
Pagination keeps a large build from flooding the agent's context: story lists come back a page at a time with an opaque cursor.
get_buildandget_pr_changesetreturn the first 25 of each list, plus aNextCursorfield per list (changedNextCursor,failedNextCursor,newNextCursor, and so on). A non-null cursor means there is more.list_build_storiesandlist_pr_storiespage the rest: passnextCursorback ascursor.limitdefaults to 25, max 100. AnextCursorofnullmeans the last page.list_buildstakes alimitinstead: default 20, max 100, newest first.render_diff_imagepaginates a tall image by pixels:pxPagination: { offset, height }returns a sliceheightdevice pixels tall (default 500) starting atoffset. It does not apply tobefore_after.
Read tools
Read tools never change anything and are annotated read-only, so a client may run them without a confirmation prompt.
| Tool | Key arguments | What it does |
|---|---|---|
list_projects | none | Every project you can access, most recently built first, each with the projectId to pass when a call needs one. |
list_builds | branch?, status?, limit?, projectId? | Recent builds, newest first, each with its gate status (pending, running, passed, changed, failed or blocked, where failed also covers a denied change) and, for a blocked one, the same blocked explanation get_build returns. The way to find a build. The status filter matches the build's raw status, which can also be preflight while a build is starting up. |
get_build | selector | Triage one build: the verdict, counts (total, changed, failed, unchanged), the first page of changed and failed stories with the AI verdict when AI review ran, and a review-comment tally. The verdict (gateStatus) reads passed once every changed or new story is accepted, whether in the dashboard, with accept_build or by the upload's auto-accept, and failed while a change is denied (each story's decision says which), while status keeps what the render found. Stories that failed, to render or on their interaction test, are not part of the verdict: they stay in failed, and a build where every story failed is failed itself. Every count is a snapshot, one story in one mode (a viewport or theme) in one browser, so on a finished build that passed or changed, total is changed + failed + unchanged plus any stories that opt out of snapshots. A blocked build also carries blocked: why it was paused and what to do next, with a message to relay to the user (on the demo project, a headline and next steps without your usage figures). |
list_build_stories | selector, status (changed, unchanged, failed), cursor?, limit? | Page through one status. unchanged lists stories identical to their baseline, once the build has settled, one row per story, so a story in three modes is one row here and three in get_build's unchanged count. |
get_pr_changeset | selector | What the whole PR does to the UI vs its base branch: counts and the first page of new, changed, and removed stories. See This PR vs base. |
list_pr_stories | selector, kind (new, changed, removed), cursor?, limit? | Page through one kind of the PR changeset. |
get_diff | selector, storyId? | Diff metrics, the AI judge's verdict and reasoning, and time-limited URLs for the baseline, candidate, and diff PNGs. Defaults to the changed stories. |
render_diff_image | diffResultId + which?, or selector + storyId; pxPagination? | The image itself as inline pixels for a vision model. which is baseline, candidate (default), diff, or before_after. |
before_after puts the baseline and candidate side by side, cropped to the changed region, with one crop per region when a story changed in several places. The storyId form returns any story's current image, including an unchanged one, and takes no which. Inline images need a client that renders image content; in a shell script, use get_diff's URLs instead.
Review tools
Review tools record the same accept, deny, and ignore decisions as the dashboard, attributed to the agent acting for you.
| Tool | Key arguments | What it does |
|---|---|---|
review_diff | diffResultId, decision (accept, deny, ignore) | Review one story. accept makes the candidate its new baseline on the branch, deny records a rejection without moving the baseline, ignore keeps the story out of the gate on future builds. |
accept_build | selector | Accept every changed story in the build at once, including ones denied earlier. Failed stories are unaffected. Returns the updated triage. |
While a story has an unresolved review comment, review_diff refuses to accept or ignore it, and accept_build accepts nothing and names the stories with open notes. Deny works despite open notes. On a build that a newer build on its branch has superseded, both tools refuse every decision, deny included, record nothing, and name the newer build to inspect with get_build. See Collaborative visual review.
Comment tools
Comment tools read and write the review threads on a build's diffs. A comment written over MCP is authored as the agent.
| Tool | Key arguments | What it does |
|---|---|---|
list_comments | selector | Every comment on the build's changed stories, plus the open comments left on earlier builds of its branch (carried: true): its diff, build, story, author (a person or an agent), body, anchor, and, on a thread's root comment, whether the thread is resolved. Pass branch instead of a build selector to read every open comment on a branch, whatever build it was left on. Project tool responses (all but list_projects) also carry openReviewComments, naming up to five branches with open comments from the last 30 days. |
post_comment | selector, diffResultId, body, anchor?, side?, parentId? | Start a thread on a diff, or reply to one with parentId. A new thread goes on the latest build on the branch; replies work on any. |
update_comment | commentId, body | Replace a comment's text. Agent-authored comments only. |
resolve_comment | commentId, resolved | Resolve (true) or reopen (false) a thread. Pass the thread's root comment id; a reply's id changes nothing. |
delete_comment | commentId | Delete one comment. Agent-authored comments only. |
A body is 1 to 4,000 characters. An anchor pins the comment on the image in coordinates normalized 0 to 1: omit it for the whole diff, or pass {type: 'point', x, y}, {type: 'rect', x, y, w, h}, or {type: 'path', points, closed}. side picks the pane: after (the candidate, default) or before (the baseline). A reply inherits its thread's side and carries no anchor.
Tool responses
Tool responses are JSON, returned both as a text block and as structuredContent that matches the tool's declared output schema. render_diff_image is the exception: it returns an image block, preceded by a text note when the story has open comment threads. An expected refusal, such as an unknown build or an invalid cursor, comes back as a tool error with a message the agent can act on.
Typical agent loop
A typical agent loop goes from a list of builds to a decision on each changed story:
- Find the build with
list_builds, or select it directly by the commit SHA or PR number from CI. - Call
get_buildfor the verdict and the changed stories, likely regressions first when AI review ran. Page further withlist_build_stories. - Read a story's verdict and reasoning with
get_diff, then look at what moved withrender_diff_imageandwhich: "before_after". - If the story has an open comment, read it with
list_comments, address it, and close it withresolve_comment. - Accept the intended change or deny the regression with
review_diff, or useaccept_buildonce every change is intended. - Optionally, check
get_pr_changesetto confirm the whole PR did only what it meant to.
What can I ask my agent?
You don't name the tools; ask in plain words and the agent picks them. Some prompts that work well:
- Did my last push change anything visually? Show me the before and after for each changed story.
- Go through the changed stories on PR 482, accept the ones this PR meant to change, and tell me which look wrong and why.
- Read the open review comments on the latest build, fix what they ask for, then resolve each thread.
- What did this pull request change in the UI compared with main, including any stories it removed?
Triage a build from your agent
Bucket real regressions vs noise and accept baselines, over MCP.
Visual testing MCP: let your agent triage the diffs
Backend agents self-correct from logs and failing tests. UI agents are blind - they say 'looks great' and ship the break. Visual testing over MCP gives the agent eyes on the actual diff.
Visual testing for agents
UI Verify is visual regression testing for Playwright, Storybook, Vitest and Bun. Your coding agent sees what its UI change did and fixes it before it ships. See how it works.
Get started