# Set up Snapvisor for this coding agent

These are official instructions from Snapvisor to set up an AI development environment for visual regression testing: your configured test suite captures screenshots, Snapvisor compares them against an eligible baseline, and people and agents review the changes. Use the commands for the installed client and test runner. Complete the applicable steps yourself by running the commands directly. Report any browser sign-in, token creation, session restart, or CI secret configuration the user must complete.

Checklist:

1. Read how Snapvisor credentials work (below). Do not create or paste any secret unless a step says so.
2. Connect the Snapvisor MCP server using the section for the agent you are.
3. If the current project has a UI test suite, install the Snapvisor SDK for it.
4. Verify the connection by running `getMe` through the MCP server (section 4 says how).
5. Print the completion message.

## 1. Credentials

- **MCP server, OAuth 2.1 (default).** A request without a token gets a `401`; compatible clients offer browser sign-in to Snapvisor. The client handles token storage after you approve access. The grant appears under Settings, Applications in the app and can be revoked there.
- **MCP server, personal access token (headless alternative).** Use it only when the user asks for a token-based setup or your client cannot open a browser. If `SNAPVISOR_ACCESS_TOKEN` is not already set, ask the user ONCE to create a token at https://app.snapvisor.io under Settings, Tokens, and to export it as `SNAPVISOR_ACCESS_TOKEN` in their shell profile. Never write the token into a file that is committed.
- **Project tokens are rejected by the MCP server.** A project's `ARGOS_TOKEN` only uploads screenshots from CI (step 3). It cannot read the API or drive the MCP server.
- **Plan.** Hosted MCP access through OAuth requires a paid plan; eligible new teams can start a 14-day Pro trial. On Free, `getMe` still verifies the connection; other OAuth operations require an upgrade. Personal access tokens use their account permissions separately.

## 2. Connect the MCP server (use the section for your agent)

The endpoint is `https://mcp.snapvisor.io` (streamable HTTP). Register it under the name `snapvisor`.

### Claude Code

- Add the Snapvisor MCP server for every project on this machine. If Claude Code answers that `snapvisor` already exists, keep it and continue.

  ```bash
  claude mcp add --transport http --scope user snapvisor https://mcp.snapvisor.io
  ```
- Sign in: the user runs `/mcp` inside Claude Code, selects `snapvisor`, and approves the Snapvisor consent screen that opens in the browser. Claude Code stores and refreshes the token itself.

With a personal access token instead:

- With `SNAPVISOR_ACCESS_TOKEN` set, register the server with the token as a header instead. No browser step.

  ```bash
  claude mcp add --transport http --scope user snapvisor https://mcp.snapvisor.io --header "Authorization: Bearer $SNAPVISOR_ACCESS_TOKEN"
  ```

### Codex

- Add the Snapvisor MCP server to Codex.

  ```bash
  codex mcp add snapvisor --url https://mcp.snapvisor.io
  ```
- Start the OAuth sign-in. It opens the Snapvisor consent screen in the browser, which the user approves.

  ```bash
  codex mcp login snapvisor
  ```

With a personal access token instead:

- Instead of the two commands above, add this table to `~/.codex/config.toml`. Codex reads the token from `SNAPVISOR_ACCESS_TOKEN` on every start.

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

### Cursor

- Add the server to `~/.cursor/mcp.json` (every project) or `.cursor/mcp.json` at the project root (this project only). If the file already exists, merge the `snapvisor` entry into its `mcpServers` object instead of replacing the file.

  ```json
  {
    "mcpServers": {
      "snapvisor": {
        "url": "https://mcp.snapvisor.io"
      }
    }
  }
  ```
- Sign in: the user opens Cursor Settings, then MCP, and completes the Snapvisor sign-in Cursor offers for `snapvisor`. If Cursor offers no sign-in, use the token variant below.

With a personal access token instead:

- Same file, with the token read from `SNAPVISOR_ACCESS_TOKEN` through Cursor's `${env:NAME}` interpolation.

  ```json
  {
    "mcpServers": {
      "snapvisor": {
        "url": "https://mcp.snapvisor.io",
        "headers": {
          "Authorization": "Bearer ${env:SNAPVISOR_ACCESS_TOKEN}"
        }
      }
    }
  }
  ```

### OpenCode

- Add the server to `~/.config/opencode/opencode.json` (every project) or `opencode.json` at the project root (this project only). If the file already exists, merge the `snapvisor` entry into its `mcp` object instead of replacing the file.

  ```json
  {
    "mcp": {
      "snapvisor": {
        "type": "remote",
        "url": "https://mcp.snapvisor.io",
        "enabled": true
      }
    }
  }
  ```
- Start the OAuth sign-in. It opens the Snapvisor consent screen in the browser, which the user approves.

  ```bash
  opencode mcp auth snapvisor
  ```

With a personal access token instead:

- Same file, with OAuth switched off and the token read from `SNAPVISOR_ACCESS_TOKEN` through OpenCode's `{env:NAME}` substitution.

  ```json
  {
    "mcp": {
      "snapvisor": {
        "type": "remote",
        "url": "https://mcp.snapvisor.io",
        "enabled": true,
        "oauth": false,
        "headers": {
          "Authorization": "Bearer {env:SNAPVISOR_ACCESS_TOKEN}"
        }
      }
    }
  }
  ```

### Any other MCP client

- Point the client at `https://mcp.snapvisor.io` over streamable HTTP. Clients that use an `mcpServers` file take this entry. A client that cannot run OAuth sends `Authorization: Bearer` followed by a personal access token.

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

## 3. SDK and CLI

- Only do this step inside a project that has a UI test suite; otherwise skip it and say so in the completion message. Use the package manager the project already uses (the lockfile tells you): the commands below are written for npm.
- Playwright (`@playwright/test` in `package.json`): install the SDK, register its reporter in `playwright.config.ts`, and capture screenshots with `argosScreenshot` in the tests that render UI.

  ```bash
  npm install --save-dev @snapvisor/playwright
  ```
- The reporter uploads from CI only, so local runs stay offline:

  ```ts
  // playwright.config.ts
  import { defineConfig } from "@playwright/test";
  import { createArgosReporterOptions } from "@snapvisor/playwright/reporter";

  export default defineConfig({
    reporter: [
      process.env.CI ? ["dot"] : ["list"],
      [
        "@snapvisor/playwright/reporter",
        createArgosReporterOptions({ uploadToArgos: !!process.env.CI }),
      ],
    ],
  });
  ```
- Storybook: install `@snapvisor/storybook`. Vitest browser mode: install `@snapvisor/vitest`. Then wire them as the SDK page describes.

  ```bash
  npm install --save-dev @snapvisor/storybook
  ```
- Any other runner that writes screenshots to a folder: install the CLI and upload that folder after the tests run.

  ```bash
  npm install --save-dev @snapvisor/cli
  npx @snapvisor/cli upload ./screenshots
  ```
- Python projects: follow the Python SDK section of https://snapvisor.io/docs/sdks.
- Uploads authenticate with the project's `ARGOS_TOKEN`, found in the project's settings at https://app.snapvisor.io. It belongs in CI secrets, never in the repository. On GitHub Actions no token is needed: https://snapvisor.io/docs/learn/integrations/github-tokenless-authentication.
- Optional: the CLI can also inspect builds, submit reviews and post comments from the terminal. `login` opens the browser for the user to approve; `whoami` confirms it.

  ```bash
  npx @snapvisor/cli login
  npx @snapvisor/cli whoami
  ```

## 4. Verify

- The `snapvisor` MCP server normally shows only two tools, `search_tools` and `execute_typescript`, and every operation is reached through them. Call `search_tools` with the query `getMe`; it answers with the declaration of `external_getMe`. Then call `execute_typescript` with this program:

  ```ts
  return await external_getMe({});
  ```
- If the server instead lists `getMe` as a tool of its own, call that tool directly. Either way, success is a response naming the signed-in user and the accounts the connection can reach; each account `slug` is the `owner` argument of every other operation.
- Most agents load MCP servers when a session starts. If no `snapvisor` tool is available to you yet, do not report failure: the completion message tells the user to restart the session and ask you to verify the connection.
- A `401` means the browser sign-in has not been completed yet. Inside `execute_typescript` a refused call throws an error carrying the same message; wrap the call in `try`/`catch` to read it. An answer that asks for an upgrade means the connection works and the account is on the Free plan.

## 5. Completion message

Print a short message to the user that states:
- which agent you configured, where (the command or file), and whether it uses OAuth or a personal access token;
- which SDK packages you installed and which files you changed, or that the SDK step was skipped and why;
- whether `getMe` succeeded, and with which user;
- what the user still has to do: approve the Snapvisor sign-in in the browser if it has not happened, restart the agent session so the Snapvisor tools load, and add the project's `ARGOS_TOKEN` as a CI secret if CI uploads were wired.

## 6. Resources

- Documentation: https://snapvisor.io/docs
- MCP server guide: https://snapvisor.io/docs/agents/mcp-server
- Access tokens: https://snapvisor.io/docs/tokens
- SDKs and CLI: https://snapvisor.io/docs/sdks
- REST API reference: https://snapvisor.io/docs/api-reference
- FAQ: https://snapvisor.io/docs/faq
- Human setup guides: https://snapvisor.io/agent-setup
- llms.txt: https://snapvisor.io/llms.txt
- Pricing: https://snapvisor.io/pricing
- Support: https://snapvisor.io/support
- Support email: support@snapvisor.io