Watchlight MCP Server

Watchlight includes a built-in MCP server that lets AI assistants work directly with your visual regression tests — running snapshots, analyzing diffs, and helping you prepare your app for Watchlight.

Your editor or AI tool starts the MCP server automatically when configured. You don't need to launch it manually.

Why use MCP with Watchlight?

With MCP connected, your AI assistant can:

• Help you update your app to work well with Watchlight (CLI arguments, stdout triggers)
• Run visual regression checks and interpret the results
• Inspect project structure, launch settings, capture triggers, baselines, and stored snapshots
• Create and update scenes directly in the project file
• Validate scene readiness before trying to run a full capture
• Fetch baseline, snapshot, latest, and diff artifacts for review
• Set or clear scene baselines as part of approval flows
• Triage failures and suggest likely causes
• Propose fixes and re-run tests to verify them

Setup

Register Watchlight as a local stdio MCP server in your editor or AI tool. The required values are:

Field	Value
Command	Path to watchlight executable (or just watchlight if it's on your PATH)
Args	mcp
Transport	stdio

Most MCP-compatible environments accept a JSON config like this:

{
  "servers": {
    "Watchlight": {
      "type": "stdio",
      "command": "watchlight",
      "args": ["mcp"]
    }
  }
}

If watchlight is not on your PATH, use the full path to the executable instead:

{
  "command": "C:/Program Files/Watchlight/watchlight.exe",
  "args": ["mcp"]
}

The exact location of this config depends on your environment:

• VS Code — add a server entry in your MCP settings (.vscode/mcp.json or settings UI)
• Cursor — add a stdio server entry in Cursor's MCP configuration
• Claude Code — run claude mcp add --transport stdio watchlight -- watchlight mcp

Once configured, the Watchlight tools and prompt appear automatically in your AI assistant.

Preparing your app for Watchlight

Watchlight works best when your app supports two things:

1. CLI arguments to launch directly into specific views (e.g. myapp --scene main-menu)
2. A stdout signal (e.g. printing [watchlight-ready]) when a view is fully loaded, so Watchlight knows when to capture

The MCP server includes a prompt that helps your AI assistant make these changes to your app. Trigger it with a slash command in your editor:

• VS Code: type /Watchlight.prepare_app_for_watchlight in the chat input
• Claude Code: type /mcp__watchlight__prepare_app_for_watchlight

The assistant will look at your project, then guide you through:

• Adding argument handling so the app can be launched into specific views
• Adding a deterministic test mode (disable animations, live clocks, unstable data where possible)
• Printing a stdout ready signal when each view finishes rendering
• Exiting cleanly after the signal in test mode
• Optionally exposing extra machine-readable state such as current route, focused control, or accessibility/tree data
• Creating a Watchlight project file with scenes that use these arguments and triggers

After that, you can run watchlight run (or ask the assistant to do it) to capture baselines and start testing.

Running tests

Once you have a Watchlight project set up, your AI assistant can run tests for you. Ask it naturally:

"Run all my Watchlight visual tests"

"Run the Main Menu scene in my Watchlight project at C:/repos/my-app/tests/watchlight/project.json"

"Re-analyze my existing Watchlight snapshots without taking new ones"

The assistant gets back structured results with pass/fail status, diff percentages, and error details for each scene.

It can also call project-inspection and artifact tools to understand what scenes exist, which snapshot is acting as the baseline, and what visual evidence should be reviewed next.

If a tool call fails because Watchlight does not support a needed capability yet, the structured error may also include a feedback hint telling the agent to ask the user to report that limitation to the Watchlight team. This is to help improve future versions.

AI-assisted triage

Where MCP really helps is when tests fail. Instead of manually inspecting diffs, you can ask:

"My Watchlight tests are failing — can you re-analyze and tell me what's wrong?"

A typical triage flow:

1. The assistant re-analyzes your project and identifies failed scenes.
2. It inspects scene metadata and fetches the relevant baseline/current/diff artifacts.
3. It checks which scenes have the highest diff percentages.
4. It looks at your recent code changes for likely causes (layout shift, theme change, missing asset, timing issue).
5. It proposes a fix, applies it, and re-runs the tests to verify.

CI + agent workflows

You can also wire Watchlight into CI with an AI agent in the loop:

1. CI runs watchlight run --strict --format json and detects visual failures.
2. An AI agent picks up the failure, calls inspect_project and re_analyze for structured context.
3. The agent fetches baseline/current/diff artifacts and inspects relevant code.
4. The agent proposes a patch, optionally updates baselines for intentional changes, and re-runs checks before opening a PR.

Notes

• The MCP server is optional. The Watchlight GUI and CLI work independently.
• The server exposes runtime, inspection, scene-authoring, validation, baseline, and artifact tools in addition to the prepare_app_for_watchlight prompt.
• Keep scene names stable so the assistant can target specific scenes reliably.

See also:

• Quick Start
• CLI & Headless
• Integration Guide