The Playwright MCP README shows the standard server setup as an npx process running @playwright/mcp@latest, with browser-state behavior handled as an explicit operating choice. For repeatable browser verification, have the agent act from an accessibility snapshot and then read the result back where a user would see it. The Playwright MCP guide explains the snapshot model; we have not run or benchmarked Playwright MCP for this guide, so we do not present its documented defaults as our test results.
Set up Playwright MCP
The Playwright MCP guide on playwright.dev lists Node.js 20 or newer as a prerequisite. The package README also states Node.js 20 or newer. Keep both page-level requirements visible rather than treating either as a guarantee about future releases, and check the current README before installing.
The standard configuration works in most MCP tools. It starts npx and passes @playwright/mcp@latest as the package argument, as shown in the Playwright MCP README:
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": ["@playwright/mcp@latest"]
}
}
}
This is an mcpServers configuration object, not a standalone file with one universal path. The documentation does not prescribe a shared file path for every MCP client, so add it through the configuration surface required by the client you run.
For Claude Code, the Playwright MCP README gives this command:
claude mcp add playwright npx @playwright/mcp@latest
Claude Code adds an MCP server at local scope by default. According to the Claude Code MCP documentation, a local server loads only in the project where you added it and remains private to your user. That scope is useful when a browser-verification setup belongs to one repository rather than every project you open.
Choose the browser state
The browser modes in the Playwright MCP README distinguish persistent profiles, isolated testing contexts, and connection to an existing browser through the extension:
| Mode | Documented behavior |
|---|---|
| Persistent profile | Runs like a regular browser and is the default. |
| Isolated context | Starts each testing session in an isolated profile. |
| Browser extension | Connects to an existing browser. |
Choose the state model before asking the agent to perform a verification. A persistent profile fits sequential browser use, while isolated mode is intended for sessions that should not share that profile. The extension mode is for workflows that need the existing browser rather than a separately managed one.
If an isolated session needs a known starting state, the README allows initial storage through the contextOptions configuration key or the --storage-state argument:
contextOptions
--storage-state
The isolated-profile guidance does not make the initial state automatic. Supply it deliberately when login state, cookies, or other browser storage must exist before the first action.
Verify repeatable browser checks
The Playwright MCP documentation says that a tool run returns a structured snapshot containing page elements, their roles, and their text. The model acts using element references from that snapshot. Build your check around that interaction path:
- Navigate to a page whose expected result you can identify in advance.
- Request
browser_snapshotand inspect the returned roles and text. - Have the agent perform the action through an element reference from the current snapshot.
- Read the resulting page state rather than assuming the action succeeded because the tool returned.
Treat a reference as part of the current interaction, not as a durable application selector your verification can store indefinitely. The useful repeatable artifact is the expected user-visible state, not a particular snapshot representation.
A screenshot has a narrower role. The Playwright MCP tool guidance says the screenshot tool captures the current page but actions cannot be performed from that screenshot; use browser_snapshot for actions. The same README describes the vision capability as coordinate-based interactions. Treat that capability description separately from the screenshot tool’s explicit action restriction rather than using a screenshot as a substitute for a structured snapshot.
In our agent operations, a new verification gate is tested with a representative case that must fail before anyone trusts it. We have seen a copied gate report PASS without exercising the relevant behavior. We have also seen a screenshot file accepted even though it showed a connection-refused page. Those incidents drive our rule: check the content of the evidence, including the expected heading or main image, rather than checking only that a file exists.
Done means the browser result has been read from the surface a user would actually see. A successful tool call, an exit code, or a saved image is a signal that something happened; it is not the final verification.
Where it breaks
Concurrent clients share a profile
The persistent-profile guidance states that one persistent profile can be used by only one browser instance at a time. Concurrent MCP clients sharing the same workspace will conflict.
For additional clients, the documented options are:
--isolated
--user-data-dir
Start an additional client with --isolated, or point it at a distinct --user-data-dir. If several agents appear configured correctly but interfere with each other, inspect profile ownership before debugging their prompts or browser instructions.
An isolated session loses its state
Closing the browser in isolated mode ends the session and loses its storage state. The Playwright MCP README says initial state must be supplied again through contextOptions or --storage-state when a later session needs it.
That behavior can look like a failed login or missing application data even though the earlier session worked. Establish the starting state before the verification action, and read the result again after any restart.
An origin filter is mistaken for a security boundary
The --allowed-origins option takes a semicolon-separated list of trusted origins. According to the Playwright MCP README, its default allows all origins, it does not affect redirects, and it is not a security boundary. The README also states directly that Playwright MCP is not a security boundary.
Use the option to express trusted browser-request origins, but do not rely on it as the control that prevents access to sensitive resources. Any actual access restriction must come from a separate security mechanism.
Assertion tools are not enabled by default
The Playwright MCP README makes its test assertion tools opt-in through this exact capability flag:
--caps=testing
If your verification workflow expects those assertion tools but the server was started without the capability, the missing tools are a configuration issue rather than evidence that the page passed.
The expected browser mode does not match the run
The browser is headed by default, while --headless switches it to headless mode, as documented in the Playwright MCP option reference:
--headless
Choose the mode before writing a check around browser visibility. Headless execution does not remove the need to inspect the resulting page content, and a headed run does not prove that the same state will be available to an isolated or restarted session.
MCP is not automatically the better CLI route
For an MCP vs CLI decision, the Playwright MCP README says coding agents increasingly favor CLI-based workflows exposed as SKILLs because CLI invocations are more token-efficient. That is the project’s stated rationale, not a benchmark from our setup. We have no measured speed or token-cost comparison, so use it as a routing consideration rather than a guaranteed result.
The practical split is simple: configure Playwright MCP when the agent needs its documented browser tools and structured interaction model. Keep an existing CLI workflow when it already provides the browser operation you need. In either case, verify the state a user can observe rather than stopping at the transport or command boundary.