Snapvisor Docs

MCP server

Connect Claude, Codex, Cursor, VS Code, Gemini, Kiro, Antigravity, or any MCP client to Snapvisor's remote MCP server at mcp.snapvisor.io to create builds, upload screenshots, run visual diffs, and approve changes — no CI pipeline required.

Snapvisor runs a remote Model Context Protocol (MCP) server so AI agents can do visual testing end-to-end. Connect once and your agent can create builds, upload screenshots, run diffs, approve or reject changes, and comment — all through the same public API, with no CI pipeline required.

Endpoint

The Snapvisor MCP server is a stateless, streamable HTTP endpoint:

https://mcp.snapvisor.io

Opening the endpoint in a browser redirects here, to this guide. Programmatic MCP clients connect over HTTP and sign in with OAuth or a personal access token (see Authentication).

Permissions

Every MCP tool is included on every plan, Free included. What a connection can do is set only by the permissions it was granted, for OAuth and personal access tokens alike. On the consent screen every permission tier is checked by default, and you can uncheck any of them:

TierCovers
ReadReading your builds, projects, teams and settings
WriteCreating and editing builds, reviews, comments and projects
DestructiveDeleting, transferring, cancelling and revoking
BillingPlans, upgrades, subscriptions and spend limits
AccountYour profile, emails, sessions, preferences, data export and account deletion
TeamMembers, invites, joining teams, SSO
ConnectionsGitHub, GitLab, Slack, Discord and Microsoft Teams connections
SupportSupport tickets
API keysPersonal access tokens and authorized apps

A call outside the granted tiers is refused with SCOPE_MISSING, whose next points at request_scopes: it gives you a one-click link to grant the missing tier. Destructive calls also ask once: the first call answers CONFIRMATION_REQUIRED with a confirmToken the agent repeats the call with, after telling you what will happen. The walkthrough is in Visual testing without CI. See Pricing.

Errors

A refused tool call returns one error object: a code, a plain-language message, a docs link to this section and, when there is a way forward, next: the tool to call and its arguments.

CodeMeaning
SCOPE_MISSINGThe connection lacks the permission tier the tool needs; next is request_scopes.
CONFIRMATION_REQUIREDA destructive call needs confirming; repeat it with next.args.confirmToken.
QUOTA_EXCEEDEDA plan limit was reached; next is upgrade_plan.
VALIDATION_ERRORAn argument is missing or invalid.
NOT_FOUNDThe build, project, team or other resource does not exist or is not visible to you.
RATE_LIMITEDToo many calls; retry later.
CONFLICTThe change conflicts with the current state, for example a name already taken.
UNAUTHORIZEDThe token is missing, expired or revoked; sign in again.
FORBIDDENYour role does not allow this action on this resource.
PAYLOAD_TOO_LARGEThe request body is too large.
TOOL_FAILEDThe tool failed on the server; the failure is reported to us.

Fastest: Add to Claude

On claude.ai, Claude Desktop, or Claude Code signed in with a Claude account, Add to Claude opens Snapvisor's listing in Claude's connector directory: click Connect, then approve the Snapvisor consent screen.

Connect from any MCP client

Snapvisor's MCP server is a hosted Streamable HTTP endpoint with OAuth 2.1 sign-in. There is nothing to install or run: point the client at the endpoint above and sign in to Snapvisor when the browser opens. The first request without a token returns a 401 that triggers the OAuth flow: your browser opens a Snapvisor consent screen, you approve the connection, and the agent is issued a scoped access token. No secrets are pasted into the client. Any client that supports remote MCP servers with OAuth works; the ones below are the common coding agents.

Claude Code

claude mcp add --transport http snapvisor https://mcp.snapvisor.io

Then run /mcp inside Claude Code and follow the browser steps to sign in (or claude mcp login snapvisor from the shell). See the Claude Code MCP docs.

Codex

Add the server with the Codex CLI, then sign in:

codex mcp add snapvisor --url https://mcp.snapvisor.io
codex mcp login snapvisor

Or add it to ~/.codex/config.toml (or .codex/config.toml in a trusted project) and run the same codex mcp login snapvisor:

[mcp_servers.snapvisor]
url = "https://mcp.snapvisor.io"

Cursor

In .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "snapvisor": {
      "url": "https://mcp.snapvisor.io"
    }
  }
}

VS Code and GitHub Copilot

Run MCP: Add Server from the Command Palette, choose HTTP, paste the URL, then pick where to save the server (for example, the workspace's .vscode/mcp.json). To write the file by hand:

{
  "servers": {
    "snapvisor": {
      "type": "http",
      "url": "https://mcp.snapvisor.io"
    }
  }
}

Gemini CLI

Since June 18, 2026, Google AI Pro/Ultra and free Gemini Code Assist accounts no longer work with Gemini CLI; it remains available with Gemini Code Assist Standard or Enterprise licenses and paid API keys. Otherwise use Antigravity.

Add the server to ~/.gemini/settings.json (httpUrl selects the Streamable HTTP transport), then run /mcp auth snapvisor to sign in:

{
  "mcpServers": {
    "snapvisor": {
      "httpUrl": "https://mcp.snapvisor.io"
    }
  }
}

Kiro

In .kiro/settings/mcp.json (workspace) or ~/.kiro/settings/mcp.json (user):

{
  "mcpServers": {
    "snapvisor": {
      "url": "https://mcp.snapvisor.io"
    }
  }
}

Google Antigravity

Antigravity and Antigravity CLI share the same config files. Both require the serverUrl key for remote servers (url and httpUrl are not supported). In ~/.gemini/config/mcp_config.json (global) or .agents/mcp_config.json (workspace):

{
  "mcpServers": {
    "snapvisor": {
      "serverUrl": "https://mcp.snapvisor.io"
    }
  }
}

Other clients

Any other MCP client that speaks streamable HTTP can connect: add a remote (HTTP) server with the endpoint above and approve the OAuth sign-in on first use.

Authentication

The server accepts two credentials:

  • OAuth 2.1 — the default browser-consent flow above. Tokens are issued per client and can be revoked at any time with the revokeAuthorizedApp tool or under Settings → Applications.
  • Personal access token — mint one under Settings → Tokens and pass it as a bearer header. Useful for headless or CI agents:
# Use a personal access token instead of the OAuth browser flow
claude mcp add --transport http snapvisor https://mcp.snapvisor.io \
  --header "Authorization: Bearer <your personal access token>"

The MCP server accepts personal access tokens and OAuth access tokens only; project (CI) tokens are rejected with a 401. Project tokens keep working on the legacy SDK routes. To create, upload to or finalize builds, or to look up a baseline, the token's user needs at least reviewer access to the project. To read a project, its builds, tests, media or settings, the token's user needs at least viewer access to it (a public project can be read by anyone); a team contributor with no access to a private project gets a 403. See Access tokens.

What agents can do

Everything you can do in Snapvisor, an agent can do through a tool. The tool surface is derived from Snapvisor's API, so it always matches what the product can do; call search_tools for the exact list. The families:

  • Builds and reviews: create builds, upload screenshots, read diffs, approve or reject changes, comment.
  • Projects: create, update, transfer and delete projects, import and link repositories, custom domains, automation rules.
  • Media: upload and share screenshots and recordings.
  • Billing: billing_status, list_plans, upgrade_plan (a Stripe Checkout link), manage_subscription, spend limits.
  • Account: profile, emails, sessions, passkeys, notification preferences, export_data, delete_account.
  • Team: members, invites, joining teams, team creation and deletion, SSO and SAML.
  • Support: create_support_ticket, list_support_tickets.
  • Connections: list_connections, get_connect_links, disconnect, reverify.
  • API keys and access: create, rotate and revoke personal access tokens, request_scopes.

Agent workflow

An agent can run a full visual test cycle without any CI integration:

getMe → listProjects → findBaselineForProject → createBuildForProject → upload files →
updateBuildForProject (final: true) → poll getBuild → listBuildDiffs → createReview
  1. Discover — call getMe to find your account slug, then listProjects to find the project name.
  2. Pick a baseline — if the project has no connected Git repository, call findBaselineForProject with commits, your ancestor commit SHAs, closest first. It answers { baseline }, where baseline is null when none of them has an eligible build. Pass baseline.head.sha as referenceCommit (and baseline.head.branch as referenceBranch) in the next step. A build that sends no referenceCommit and whose parentCommits match nothing is compared against the latest approved build on its referenceBranch (the default base branch when unset), else the latest completed one. Only the new build itself is excluded, so a build on the default branch is compared against the previous build on that branch. With no build on that branch it is compared against nothing, so every screenshot then shows as added. A referenceCommit with no eligible build (finished, passed, not rejected, approved) is never replaced by another one: that build is compared against nothing too. The very first build has no baseline and needs no approval: it is stored as the one later builds compare against. See how the baseline is chosen.
  3. Create — call createBuildForProject with a commit SHA and branch. The response includes signed upload URLs for each screenshot the server doesn't already have.
  4. Upload — this step is not a tool call. Send each screenshot file as a multipart/form-data POST to its postUrl, with every entry of fields as a form field and the file itself last, as file. The agent needs to be able to make HTTP requests and read the screenshot files, as coding agents (Claude Code, Codex, Cursor) can from their shell. A client that cannot make that POST can call uploadScreenshotForProject once per screenshot instead, with the bytes base64-encoded (up to 700 KB each); it returns the key for the next step.
  5. Finalize — call updateBuildForProject with final: true to start diff processing.
  6. Poll — call getBuild while status is pending or progress. It then settles on no-changes (nothing to review), changes-detected (review needed), or error, aborted or expired.
  7. Review — call listBuildDiffs to inspect the changes, then createReview with event: "APPROVE" or "REJECT". The build's status becomes accepted or rejected.

How the tools are exposed

The server keeps your agent's context small: instead of listing every operation as its own tool, it exposes two.

  • search_tools returns the operations that match a query, as TypeScript declarations such as external_getMe or external_listBuilds.
  • execute_typescript runs a short program that calls those functions, so several calls cost one round trip.

Every call enforces the same authentication, permissions and plan limits as a direct call. A destructive call is confirmed in a new execute_typescript call, after the agent has told you what it will do: a confirmToken presented in the same program that received it is refused. To check a connection, run return await external_getMe({}); through execute_typescript: it answers with the signed-in user and the accounts the connection can reach.

More on connecting agents

The MCP server overview on snapvisor.io covers what the server is for and its discovery documents, and the agent setup pages give a copy-paste prompt for Claude Code, Codex, Cursor and OpenCode.

On this page