UI Verify MCP server: tool reference

Every tool is confined to one project: the one whose key the client connects with. This page lists each tool with its key arguments and what it returns, for wiring the server into Claude Code, Cursor, or any MCP client. For the review workflow itself, see Triage visual changes from your coding agent.

The UI Verify MCP endpoint is https://uiverify.ai/api/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.

The server authenticates with your project API key (uv_proj_...), sent as a Bearer token in the Authorization header. It is the same key your CI uses for uiverify upload. In Claude Code:

The key is referenced as the UIVERIFY_API_KEY env var, single-quoted so your shell does not expand it when you add the server. Claude Code expands it at runtime, so the committed .mcp.json never holds the secret. Your project setup page shows the same command, and any other MCP client takes the same URL and header. Restart the agent session after adding it so the tools load.

No. The initialize handshake and tools/list answer without a key, so any client or MCP directory can discover the tool names and schemas. Calling a tool does need the key: without one, the call returns an error asking you to connect with your uv_proj_ key, and no data. Every read and write is scoped to the key's project, so a build from another project reads as not found.

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.

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 keeps a large build from flooding the agent's context: story lists come back a page at a time with an opaque cursor.

• get_build and get_pr_changeset return the first 25 of each list, plus a NextCursor field per list (changedNextCursor, failedNextCursor, newNextCursor, and so on). A non-null cursor means there is more.
• list_build_stories and list_pr_stories page the rest: pass nextCursor back as cursor. limit defaults to 25, max 100. A nextCursor of null means the last page.
• list_builds takes a limit instead: default 20, max 100, newest first.
• render_diff_image paginates a tall image by pixels: pxPagination: { offset, height } returns a slice height device pixels tall (default 500) starting at offset.

Read tools never change anything and are annotated read-only, so a client may run them without a confirmation prompt.

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. Inline images need a client that renders image content; in a shell script, use get_diff's URLs instead.

Review tools record the same accept, deny, and ignore decisions as the dashboard, attributed to your project key.

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 always works. See Collaborative visual review.

Comment tools read and write the review threads on a build's diffs. They are available when review comments are enabled for your team; otherwise a call returns an error saying so. A comment written over MCP is authored as the agent.

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 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.

A typical agent loop goes from a list of builds to a decision on each changed story:

1. Find the build with list_builds, or select it directly by the commit SHA or PR number from CI.
2. Call get_build for the verdict and the changed stories, likely regressions first when AI review ran. Page further with list_build_stories.
3. Read a story's verdict and reasoning with get_diff, then look at what moved with render_diff_image and which: "before_after".
4. If the story has an open comment, read it with list_comments, address it, and close it with resolve_comment.
5. Accept the intended change or deny the regression with review_diff, or use accept_build once every change is intended.
6. Optionally, check get_pr_changeset to confirm the whole PR did only what it meant to.