---
title: Write Playwright browser checks with Claude, Cursor or any MCP agent
description: Connect Claude, Cursor or another MCP client to WatchFor and let it write a Playwright browser check, test-run it in our browsers, read the failed step, fix it and create the check — with a ready prompt.
canonical: https://watchfor.io/docs/monitors/browser-checks/agents
---

# Write Playwright browser checks with Claude, Cursor or any MCP agent

Connect Claude, Cursor or another MCP client to WatchFor and let it write a Playwright browser check, test-run it in our browsers, read the failed step, fix it and create the check — with a ready prompt.

Your coding agent can do the whole loop for you: write the script, run it in
our browsers, read what failed, fix it, and create the check once it passes.
It works through the WatchFor [MCP server](/docs/api/mcp), with the same
permissions and limits as the API — and it asks before it creates anything.

The dashboard has the same prompt behind **New browser check → Ask your agent**,
with your goal and URL filled in.

## 1. Connect your agent

The server is `https://watchfor.io/api/mcp`. Clients that support OAuth need no
key: add the server, approve access in the browser, done.

**Claude Code**

```bash
claude mcp add --transport http watchfor https://watchfor.io/api/mcp
```

Then run `/mcp` in Claude Code and authenticate in the browser.

**Cursor / JSON config**

```json
{
  "mcpServers": {
    "watchfor": {
      "url": "https://watchfor.io/api/mcp",
      "headers": { "Authorization": "Bearer wf_live_YOUR_KEY" }
    }
  }
}
```

Create a key with the **write** scope in **Settings › API keys**. A read-only
key can inspect runs but can't start test runs or create checks.

**Claude.ai**

**Settings → Connectors → Add custom connector** → `https://watchfor.io/api/mcp`.
Claude walks you through the consent screen.

## 2. Paste the prompt

Replace the goal and the site, then paste it into your agent:

```text
Write a WatchFor browser check (a Playwright Test script) for this journey, using the WatchFor MCP tools.

Goal: <what must keep working, e.g. a customer can sign in and see their orders>
Site: <https://your-site.example>

1. Write one @playwright/test file: import { test, expect } from '@playwright/test', one test() with a test.step() per step a person would name. Read the site from process.env.TARGET_URL and credentials from process.env (for example process.env.LOGIN_PASSWORD) — never put a password in the script. Prefer getByRole / getByLabel locators and web-first expect() assertions; no fixed waits. Only @playwright/test, otpauth, @faker-js/faker and Node built-ins can be imported.
2. Run it with test_playwright_script (script, target = the site). The result has the status, the failed step with its error and code frame, console errors and failed requests. If it is still running, poll get_playwright_run with the test_run_id.
3. If it failed, read the failed step's error and fix the script (a selector that matched nothing or several elements, a missing wait, a redirect). If missing_variables is not empty, stop and ask me to add them in WatchFor under Settings → Variables & secrets (passwords as secrets). If the site itself is broken, tell me instead of weakening the test.
4. Repeat until a run passes, at most 5 runs. Show me the final script and the last result.
5. Only after I confirm: call list_locations, pick a location with browser: true, and call create_monitor with type "playwright", a name of at most 50 characters, target = the site, interval 600, locations = [that id] and config = { script }.
```

## What happens

| Step | Tool | What the agent gets back |
|---|---|---|
| Try the script | `test_playwright_script` | The run: status, the failed step with its error and code frame, console errors, failed requests, Web Vitals, and `missing_variables` |
| Still running? | `get_playwright_run` | The same run by `test_run_id` |
| Pick where it runs | `list_locations` | Locations; `browser: true` marks the ones that run browser checks |
| Keep it | `create_monitor` | The new check (`type: "playwright"`, `config.script`) |

Every test run counts against your plan's test runs per hour, the same as the
**Test run** button, and an organization can have 3 going at once.
`test_playwright_script` is marked as a tool that acts on the outside world,
so your MCP client asks before it runs your agent's script. A script error (a bad import, no test) comes back at once
naming the line, without using a run.

## Good to know

- **Secrets stay yours.** The prompt tells the agent to read credentials from
  `process.env` and to ask you to add them under **Settings › Variables &
  secrets**. It never needs to see a password, and the run results it reads
  have secrets masked.
- **A failing site isn't a failing script.** The prompt asks the agent to say
  so rather than weaken the test until it passes. The
  [troubleshooting guide](/docs/monitors/browser-checks/troubleshooting) is a
  good page to point it at.
- **Check the result.** Read the final script like a pull request: assertions
  that prove the journey worked (not just that a page loaded), no fixed waits,
  no credentials inlined.
- **Existing checks too.** Ask it to fetch the last failed run of a check with
  `list_playwright_runs` and `get_playwright_run`, explain it, and propose a
  fix you apply in the editor.

---

Canonical page: https://watchfor.io/docs/monitors/browser-checks/agents · All docs: https://watchfor.io/docs · Site guide: https://watchfor.io/llms.txt