How to Maintain Tests with the Applitools MCP Server

The Applitools MCP Server connects an MCP-capable assistant to Applitools Eyes so you can configure supported visual tests, inspect existing results, investigate differences, and prepare resolution decisions from your client. A visual difference is a review item, not automatically a defect or a safe baseline update.

There is an important framework boundary: the documented setup and checkpoint-authoring tools support the Playwright TypeScript/JavaScript Fixtures SDK. Inspection, review, and resolution tools work with existing Eyes results regardless of which supported SDK or language produced them. The server requires Node.js 18 or newer and an MCP-capable client. Applitools MCP Server documentation

1. Check whether the tools fit your project

What you want to do	Supported scope	What you need
Set up Eyes in a project	Playwright TypeScript/JavaScript Fixtures	Source-code access, Node.js 18+, MCP client
Configure Ultrafast Grid (UFG)	Playwright TypeScript/JavaScript Fixtures	Source-code access, Node.js 18+, MCP client
Add checkpoints to tests	Playwright TypeScript/JavaScript Fixtures	Source-code access, Node.js 18+, MCP client
Inspect or review captured results	Existing Eyes results across SDKs and languages	Read key; DOM inspection also depends on DOM capture having been enabled for the run
Resolve results or change match regions	Existing Eyes results across SDKs and languages	Write key; saving or resetting requires explicit approval

If your project is not using Playwright Fixtures, you can still use the MCP server to examine and resolve existing Eyes results. The documented setup and checkpoint tools are not a general-purpose authoring interface for every SDK.

2. Install and connect the server

Applitools recommends its VS Code or Cursor extensions, which can install and connect the server for those clients. For a manual setup, add a stdio server entry to the MCP configuration used by your client. Client-specific configuration locations and setup steps vary; consult the current instructions for that client.

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

This configuration asks npx to run the current @applitools/mcp package. Restart or reload the MCP client if its instructions require it before expecting the server’s tools to appear.

3. Configure only the credentials needed

The keys have separate purposes. APPLITOOLS_API_KEY is for running Eyes tests. APPLITOOLS_READ_KEY is for inspection and review. APPLITOOLS_WRITE_KEY is for resolution and for review in resolve mode. A read-only investigation does not require a write key. Use the least access needed for the task.

For example, provide a read key to enable inspection without enabling baseline changes:

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

Add APPLITOOLS_WRITE_KEY only for workflows that need resolution. Add APPLITOOLS_API_KEY when the requested work includes test execution. The documentation says key values are not included in logs, errors, or tool responses. If a required key is missing, the tool reports which key is needed.

4. Set up Eyes and add checkpoints (Playwright Fixtures only)

With access to the Playwright project’s source, ask the assistant to verify the API key and guide project setup. The documented tool names include eyes_verify_api_key, eyes_setup_project, eyes_setup_ufg, and eyes_add_checkpoints_to_test. Setup and checkpoint authoring are scoped to the Playwright TypeScript/JavaScript Fixtures SDK; follow the current Playwright and SDK version guidance in the Applitools documentation.

Ask the assistant to verify the key and, where applicable, the Eyes server connection.
Review the proposed project configuration and code edits. The setup workflow can configure the Eyes reporter and add settings and dependency imports.
Ask for checkpoints at meaningful UI states, such as after the page has reached the state your test intends to validate.
Run your project’s normal visual tests and inspect the resulting batch in Eyes.

Eyes captures screenshots and compares them with stored baselines. A baseline is the expected appearance for a test state and environment. Differences may come from an intentional design update, a defect, unstable content, or a mismatch in test conditions; investigate the evidence before deciding.

5. Investigate a visual failure before changing a baseline

Use the narrowest scope that contains the problem: batch, scenario, session, or step. Inspection can expose session and batch information, DOM differences, DOM searches, active match regions, and a node’s history across runs. The review workflow can gather evidence such as images, DOM differences, and history before reporting findings.

Try read-only prompts first:

“Review my last batch and tell me what changed.”
“Just show me what changed in this batch, don’t resolve anything yet.”
“Is this diff on the timestamp element dynamic, or a real change?”

When reviewing the findings, compare the changed image region with the baseline, check whether the same change appears in related sessions, and use DOM differences or node history when available. A recurring timestamp or other dynamic element may need investigation of the test data or match regions; do not assume that a repeated change is harmless. If DOM capture was not enabled when the test ran, DOM-based evidence may be unavailable, and the sessions tool may return no data.

6. Resolve deliberately and save only after review

Review can run in inspect mode or resolve mode. Resolve mode needs both the read and write keys; resolution tools need a write key. Resolution can accept or reject checkpoints and add, remove, or update match regions. Depending on the decision, effects may apply to steps with the identical diff and related sibling sessions with the same scenario name.

Reviewing is not the same as committing a baseline. Saving accepted or rejected changes is a separate request through eyes_resolve_save. Resetting a session or batch to the revision it originally ran against is a separate request through eyes_resolve_reset. Both save and reset require explicit approval. Keep the investigation read-only until the evidence and intended outcome are clear.

Ask for an inspect-mode review and specify the batch, scenario, session, or step.
Read the explanation and inspect the supporting images, DOM evidence, and history that are available.
If a change is intentional, request a resolution decision and review which steps or regions it affects.
Only when ready to commit, request the separate save action and approve it explicitly. Use reset only when restoring the original run baseline is the intended outcome.

For example: “Reset this batch’s baseline to what it originally ran against” describes a mutating action. Treat it as a separate, approval-gated reset request, not as part of an ordinary review.

7. Troubleshooting

Symptom	Likely cause	What to do
The Applitools tools do not appear in the assistant	The MCP server is not configured for this client, the client has not reloaded, or the command could not run.	Check the client’s current MCP setup instructions, confirm Node.js 18 or newer is available, verify the stdio command and arguments, then reload or restart the client as directed.
A tool reports a missing key	The requested operation needs a credential that is not configured.	Use the reported requirement: API key for execution, read key for inspection, and write key for resolution or resolve-mode review. Keep read-only work read-only.
Setup or checkpoint authoring does not fit the project	The project is not using the supported Playwright TypeScript/JavaScript Fixtures SDK.	Use the MCP server for inspection and review of existing Eyes results, which are supported across SDKs; author setup/checkpoint code through the supported workflow.
DOM inspection returns no useful data	DOM capture may not have been enabled when the test ran.	Use image and batch/session evidence available for that run. Enable DOM capture for future runs if DOM-based investigation is needed.
A visual difference appears to be dynamic	The page may contain changing content, but the difference alone does not prove that it is harmless.	Compare the image and DOM evidence, inspect node history across runs, and decide whether the content should be stabilized or handled with an appropriate match region.
A baseline seems unchanged after review	Review reports findings; it does not itself save baseline changes.	After a deliberate resolution decision, request the separate save operation and provide explicit approval.
A reset request is blocked or prompts for approval	Reset is a mutating action and requires a write key and explicit approval.	Confirm the intended batch or session and approve the separate reset request only when restoring the original run baseline is correct.

8. Reliability, speed, and operating cost

The MCP server is an assistant interface to Eyes workflows; it does not replace the test run that captures visual results. Setup/checkpoint assistance also depends on access to source code and the supported Playwright Fixtures project type. Inspection quality depends on what the test run captured, especially when a question calls for DOM evidence.

For predictable triage, identify the batch and target scope, ask for inspect mode first, and provide a focused question about the observed change. This makes it easier to separate evidence gathering from a later resolution request. The supplied documentation does not establish performance benchmarks or a specific pricing model, so evaluate timing and service cost against your team’s existing Applitools plan and workload.

Or skip the browser setup

If the task is to capture a page image rather than maintain an Eyes visual-test baseline, ScreenshotNeo offers a single-request screenshot API and an MCP server for AI agents. Cookie banners, popups, and chat widgets are removed before the shot; bot checks, blank pages, and failed loads are never billed. The MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card, and paid plans start at $5 for 3,000. Every feature is on every plan. See the ScreenshotNeo API documentation.

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

ScreenshotNeo returns a screenshot or PDF from one GET request. Its response headers report the page verdict and billing status. Learn more at ScreenshotNeo, then sign up for 1,000 free screenshots a month with no card.

FAQ

Can I use the MCP server if my tests were written in another language?

Yes, to inspect, review, and resolve existing Eyes results. The documented setup and checkpoint-authoring tools have the narrower Playwright TypeScript/JavaScript Fixtures scope.

Does the assistant automatically accept visual changes?

Review can recommend or prepare resolution decisions, but saving or resetting a baseline is separate and requires explicit approval.

Do I need all three API keys?

No. Supply the keys required by the operation: execution, read, and write credentials serve different purposes.

Can I investigate a run without DOM capture?

You can use other available result evidence, such as images and batch/session information. DOM-based inspection depends on DOM data having been captured for that run.

Sources

Applitools MCP Server documentation — installation, requirements, key permissions, tool scope, and approval behavior.
Applitools Storybook quick start — visual screenshot comparison and baseline review context.