# MCP server

Canonical: https://snapvisor.io/docs/agents/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.

<ConnectPill />

## Endpoint [#endpoint]

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

```text
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](#authentication)).

## Permissions [#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:

| Tier        | Covers                                                                        |
| ----------- | ----------------------------------------------------------------------------- |
| Read        | Reading your builds, projects, teams and settings                             |
| Write       | Creating and editing builds, reviews, comments and projects                   |
| Destructive | Deleting, transferring, cancelling and revoking                               |
| Billing     | Plans, upgrades, subscriptions and spend limits                               |
| Account     | Your profile, emails, sessions, preferences, data export and account deletion |
| Team        | Members, invites, joining teams, SSO                                          |
| Connections | GitHub, GitLab, Slack, Discord and Microsoft Teams connections                |
| Support     | Support tickets                                                               |
| API keys    | Personal 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](/agents/visual-testing-without-ci). See [Pricing](/pricing).

## Errors [#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.

| Code                    | Meaning                                                                              |
| ----------------------- | ------------------------------------------------------------------------------------ |
| `SCOPE_MISSING`         | The connection lacks the permission tier the tool needs; `next` is `request_scopes`. |
| `CONFIRMATION_REQUIRED` | A destructive call needs confirming; repeat it with `next.args.confirmToken`.        |
| `QUOTA_EXCEEDED`        | A plan limit was reached; `next` is `upgrade_plan`.                                  |
| `VALIDATION_ERROR`      | An argument is missing or invalid.                                                   |
| `NOT_FOUND`             | The build, project, team or other resource does not exist or is not visible to you.  |
| `RATE_LIMITED`          | Too many calls; retry later.                                                         |
| `CONFLICT`              | The change conflicts with the current state, for example a name already taken.       |
| `UNAUTHORIZED`          | The token is missing, expired or revoked; sign in again.                             |
| `FORBIDDEN`             | Your role does not allow this action on this resource.                               |
| `PAYLOAD_TOO_LARGE`     | The request body is too large.                                                       |
| `TOOL_FAILED`           | The tool failed on the server; the failure is reported to us.                        |

## Connect from any MCP client [#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-code]

```bash
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](https://code.claude.com/docs/en/mcp).

### Codex [#codex]

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

```bash
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`:

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

### Cursor [#cursor]

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

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

### VS Code and GitHub Copilot [#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:

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

### Gemini CLI [#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](#google-antigravity).

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

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

### Kiro [#kiro]

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

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

### Google Antigravity [#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):

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

### Other clients [#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 [#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:

```bash
# 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>"
```

<Callout type="warn">
  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](/tokens).
</Callout>

## What agents can do [#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 [#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](/agents/visual-testing-without-ci#how-the-baseline-is-chosen-without-a-repository).
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 [#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 [#more-on-connecting-agents]

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

