ScreenshotNeo
Sign in Get a free key

BlogAI agents

How to Set Up Visual Testing with the Applitools MCP Server

Connect an MCP client to Applitools Eyes, add Playwright visual checkpoints, and learn how keys, baselines, and result review fit together.

By the ScreenshotNeo team4 October 20269 min read

The Applitools MCP server connects a compatible AI assistant to Applitools Eyes workflows. It can help configure a supported Playwright project, add visual checkpoints, and inspect or resolve visual results. The Eyes SDK still runs the tests: the MCP server is an assistant interface and setup aid, not a test runner replacement.

For automated setup and checkpoint insertion, the documented project scope is Playwright with the Applitools Playwright JavaScript/TypeScript Fixtures SDK. Result inspection and resolution can work with Eyes results produced by supported SDKs and languages more broadly. You need Node.js 18 or newer, a compatible MCP client, access to the project source, and the appropriate Applitools credentials.

1. Check the prerequisites and choose a setup path

You can connect through an Applitools VS Code or Cursor extension, which manages the server connection, or register the server manually in your MCP client. Use the extension when it matches your editor and you want less configuration to maintain. Use manual setup when you need direct control over the MCP server entry or use another compatible client.

  • Install Node.js 18 or newer.
  • Use an MCP client with support for the documented MCP configuration, such as VS Code/Copilot, Cursor, Cline, or Claude Code.
  • For assistant-driven project setup and checkpoint edits, confirm the project uses Playwright and the Applitools JavaScript/TypeScript Fixtures SDK.
  • Have access to the project files so you can inspect and review edits the assistant proposes.

The client-specific configuration location and registration command vary. Use Applitools’ official MCP documentation for the current steps for your client. The manual stdio form below is the general configuration pattern.

2. Register the MCP server

Add a server entry to the MCP configuration used by your client. This invokes the package through npx and uses the moving @latest package tag:

{
  "mcpServers": {
    "applitools-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["--yes", "@applitools/mcp@latest"]
    }
  }
}

The extension path may manage this connection for you. With a manual entry, save it in the client-specific location, then restart or reload the client if its MCP workflow requires that. Since @latest can change over time, check the official instructions when troubleshooting a setup that used to work.

3. Configure the right Applitools keys

There are three distinct credentials in the documented workflow. Do not substitute one for another:

Variable Purpose When you need it
APPLITOOLS_API_KEY Execution key for running Eyes visual tests Project setup and test execution
APPLITOOLS_READ_KEY Read-only key for inspection tools and review in inspect mode When the assistant needs to inspect Eyes results
APPLITOOLS_WRITE_KEY Write-only key for resolution tools and review in resolve mode; resolve is the documented default When the assistant needs to resolve results

Keys can be provided as environment variables, in a project .env file, or in the MCP server configuration. The setup tool can search common project and environment configuration locations for the execution key. For a manual MCP setup, the configuration can include the keys like this:

{
  "mcpServers": {
    "applitools-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["--yes", "@applitools/mcp@latest"],
      "env": {
        "APPLITOOLS_API_KEY": "<execution-key>",
        "APPLITOOLS_READ_KEY": "<read-only-key>",
        "APPLITOOLS_WRITE_KEY": "<write-only-key>"
      }
    }
  }
}

Replace placeholders locally. Never commit real keys or paste them into a public prompt, issue, or repository. Give the assistant only the read or write access its task needs. The execution key does not replace the separate read and write credentials for newer inspection and resolution workflows.

4. Ask the assistant to configure Eyes and add a checkpoint

Once the server is connected and the key is available, use a narrow request that states the project and intended test. For example:

Verify the Applitools execution API key available to this project. Set up Eyes for this Playwright JavaScript/TypeScript Fixtures project, then add a visual checkpoint to the existing login.spec test after a successful login. Show me the files you changed and explain how to run the test.

The setup tools can configure the Eyes reporter and project settings, and checkpoint tools can add visual checks to supported tests. Review the generated changes before running them: check that the checkpoint is after the UI reaches the intended state, that test data is stable, and that secrets remain outside source control. The assistant’s file edits are not a substitute for code review.

If the goal is to inspect existing results, ask for inspection explicitly and provide a read key. If the goal is resolution, provide the write key and review the proposed action carefully. Applitools documents that the assistant requests explicit approval before committing a change to a baseline. Treat that approval as a human review decision, especially where a changed baseline could hide a regression.

5. Run the test, establish a baseline, and inspect changes

  1. Run the Playwright test using the project’s existing test command. The Eyes SDK performs the test execution.
  2. For an initial visual check, review the result and establish or accept a baseline only after confirming the rendered page is the intended reference.
  3. On later runs, inspect visual differences and decide whether they reflect an expected design change or a defect.
  4. If you need broader cross-browser or device coverage, ask the assistant to configure the Ultrafast Grid (UFG), then review the configuration and results.
  5. Use the MCP inspection and resolution workflows where appropriate. Keep baseline acceptance deliberate; do not treat a passing test or an assistant suggestion as automatic approval.

Applitools’ documented workflow is to configure the server and key, ask the assistant to add visual checks, run the test to establish a baseline, and inspect differences on later work. This describes the vendor’s workflow, not an independent performance or accuracy evaluation.

6. Know which tasks the MCP server supports

Task What to expect
Configure Eyes in a project Setup tools are for Playwright projects using the JavaScript/TypeScript Fixtures SDK.
Add visual checkpoints Checkpoint editing has the same documented Playwright Fixtures scope.
Inspect Eyes results Inspection tools work against Eyes results from supported SDKs/languages; a read key is required.
Resolve results Resolution tools require a write key.
Review a baseline change The assistant requests explicit approval before committing a change to a baseline.
Execute visual tests The Eyes SDK remains responsible for test execution; MCP provides the assistant interface.

That distinction matters for teams whose tests are not Playwright JavaScript/TypeScript Fixtures. They may still use result workflows documented for supported SDKs, but should not assume the setup and checkpoint editing tools support their project framework.

7. Troubleshooting

Symptom Likely cause What to do
The MCP server does not appear in the client The config is in the wrong client-specific location, has invalid JSON, or the client has not reloaded it. Validate the JSON, confirm the config path for your client in the official instructions, and restart or reload the client.
npx cannot start the package Node.js is missing or older than the documented minimum, or package retrieval failed. Check that Node.js is version 18 or newer and that the environment running the client can invoke npx and retrieve the package.
The assistant cannot verify or configure the project key The execution key is missing, misspelled, unavailable to the server process, or stored in a location the setup tool did not search. Set APPLITOOLS_API_KEY where the client process can read it, or configure it in the MCP entry or project environment as appropriate. Do not use the read or write key for execution.
Inspection returns an authorization error The read key is absent or the wrong key type was supplied. Configure APPLITOOLS_READ_KEY for inspection and inspect-mode review.
Resolution is unavailable or unauthorized The write key is missing or the task is using a read-only key. Configure APPLITOOLS_WRITE_KEY for resolution. Review the proposed baseline action and approve it only when intended.
The assistant refuses to add a checkpoint to another framework Automated setup and checkpoint editing have narrower support than result inspection. Use the documented Playwright JavaScript/TypeScript Fixtures project scope for these tools. Check official documentation for current supported options rather than assuming the broader inspection support applies.
Tests run but no useful comparison appears The checkpoint may be at the wrong state, the page may not have finished rendering, or a baseline has not been established. Place the checkpoint after the relevant UI state is stable, use deterministic test data, run the test, and review the initial result to establish the intended baseline.
A visual difference appears on every run The test may capture dynamic content, such as changing data or time-dependent UI. Stabilize the test inputs and capture state, then inspect each difference before updating a baseline. The MCP server does not make a changing page deterministic by itself.

8. Performance, reliability, and maintenance

The available setup sources do not publish independent speed, accuracy, coverage, or uptime benchmarks for the MCP server, so plan capacity from your own project runs rather than assumed figures. The server helps an assistant set up and interact with Eyes; actual test execution and visual comparison remain part of the Eyes SDK workflow.

  • Keep captures stable: deterministic data and a checkpoint taken after the intended page state make visual differences easier to interpret.
  • Separate credentials by task: use the execution key for tests, the read key for inspection, and the write key only for actions that need it.
  • Review generated edits: verify reporter and project configuration, checkpoint placement, and secret handling before relying on the test.
  • Review baselines as code changes: an intentional visual update can be accepted, but an unexplained difference should be investigated before resolution.
  • Maintain the connection: the example uses @latest, which is not a pinned package release. Recheck current vendor instructions if package behavior, client support, or configuration changes.

The supplied documentation does not establish pricing, cost per test, or resource use for a given suite. Consult Applitools’ current product and plan information for commercial terms; do not infer cost from the MCP configuration.

Or skip the browser setup

If you need screenshots as test artifacts or for an AI workflow and do not want to maintain browser capture code, ScreenshotNeo is a website screenshot API and MCP server from Yorker Media. Its one-call API returns an image or PDF, and its MCP server gives AI agents tools to take screenshots, inspect page information, and capture PDFs. It complements a visual-testing workflow; it does not replace Applitools Eyes baselines or the Eyes SDK.

Cookie banners are accepted and removed before capture, along with known consent platforms, newsletter popups, and chat widgets. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers report the page verdict and billing status. One thousand screenshots per month are free with no card; paid plans start at $5 for 3,000 screenshots.

cURL:

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

Python:

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

Node.js:

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await Bun.write('shot.webp', res);

See the ScreenshotNeo API documentation for request options. Each step of cookie and popup cleanup can be turned off. Capture full pages, a CSS-selected element, or PDF; set viewport or device, dark mode, retina scale, wait conditions, headers, cookies, user agent, timezone, geolocation, custom CSS or JavaScript, click and hide selectors, request blocking, resize, cache TTL, signed image links, asynchronous jobs with signed webhooks, bulk captures of up to 100 URLs per call, and usage through the API. The API also accepts parameter names used by other screenshot APIs to ease migration.

Sign up for 1,000 free screenshots a month with no card.

Frequently asked questions

Does the Applitools MCP server run my Playwright tests?

No. It helps the assistant configure and interact with Eyes workflows; the Eyes SDK runs visual tests.

Can I use the setup tools with another test framework?

The documented automated setup and checkpoint tools target Playwright JavaScript/TypeScript Fixtures. Inspection and resolution tools have broader support for Eyes results from supported SDKs and languages.

Do I need all three Applitools keys?

No. Use the execution key for tests. Add the read key for inspection and the write key for resolution when those workflows are needed.

Does a visual change automatically become the new baseline?

No. Review the difference and treat baseline changes as an explicit decision; the documented assistant workflow asks for approval before committing one.

Sources

Keep reading