Playwright MCP: setup, logins and safe limits

Playwright MCP is Microsoft’s MCP server that lets an agent drive a real browser step by step through accessibility snapshots, started with npx @playwright/mcp@latest. Use it for multi-step, stateful browser flows. When the job is only getting page data, use a plain script or a data-tool MCP server (search, scrape, crawl), which returns the data in one call.

You have added Playwright MCP to your MCP client and the first page loads. Then come the questions the README leaves to you: whether a login survives a restart, how to attach a browser the server didn’t launch, what the agent can reach, and why a site returns a block page.

By the end, you can pick the server or tool that fits each job and configure Playwright MCP so the agent reaches only what it should.

Key Takeaways

• Refs like e5 are valid only for the snapshot they came from, so re-snapshot after the page changes.
• A browser attached with --cdp-endpoint is never closed by the idle timeout, so you handle cleanup.
• The package is still pre-1.0 (releases): pin versions, recheck flags.
• A hosted Wayfern instance takes about 45 to 50 seconds to cold start, and the first tool call waits.

What is Playwright MCP and how does it work?

Playwright MCP is a Model Context Protocol server from Microsoft that lets an AI agent drive a real browser through Playwright. Instead of screenshots, it returns structured accessibility snapshots of the page, and the agent acts on elements by reference.

The snapshot is plain text: a tree of roles and names taken from Playwright’s accessibility tree rather than from pixels. That’s why the playwright.dev docs say it needs “no vision models”. Each element the agent can act on carries a ref, such as e5.

Playwright’s todomvc example shows the loop. The agent calls browser_navigate with https://demo.playwright.dev/todomvc. The snapshot that comes back lists textbox "What needs to be done?" [ref=e5].

The agent then calls browser_type with target: "e5", text: "Buy groceries" and submit: true, and the server answers with another snapshot.

A ref is a label the server printed into one snapshot, so treat it as a pointer into that snapshot rather than a stable selector. After the page re-renders or navigates, read refs from the newest snapshot.

Every tool call in the example returns a snapshot, so a long flow means many round trips and many snapshots of tokens.

A minimal client config looks like this:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}

For the Node.js minimum, read the engines field in the package’s package.json.

The releases page shows the package is still pre-1.0, so flags and tool names can change between releases. Before you copy a config from an older post, check the README options table for the current --caps groups, headed mode and browser choice.

What happens to cookies and login state between sessions?

Playwright MCP keeps cookies and login state according to the profile mode you start it in: a persistent profile on disk (the default), an in-memory profile with --isolated, or your own running browser through the extension.

	Persistent (default)	--isolated	Extension
Where state lives	Profile directory on disk	Server’s memory	Your running browser
What survives	Cookies and storage between sessions	Nothing	Whatever that browser keeps
What is lost	Only what you delete	Everything when the session ends	Nothing from the server’s side

The Playwright MCP README places the default profile under mcp-{channel}-{workspace-hash} in the platform cache directory. The hash ties the profile to your workspace, so two projects don’t share a login.

To choose the location yourself, pass --user-data-dir, which the README describes as the “path to the user data directory”.

With --isolated, the server will “keep the browser profile in memory, do not save it to disk”. To start such a session already signed in, add --storage-state, the “path to the storage state file for isolated sessions”.

The storage state file seeds the session only. Anything the agent changes after that is gone when the session ends unless you save it.

The --caps=storage option adds cookie and storage tools, so the agent can read or set them mid-flow. Use them sparingly, since cookie values then pass through the model’s context.

The --idle-timeout option closes the browser after the session sits idle. On a persistent profile, cookies written to disk remain for the next launch. In an isolated session, an idle close loses the whole profile.

A browser attached by extension or --cdp-endpoint is never closed by the idle timeout, so cleanup stays with you.

If a flow needs a login, choose where that state lives before the first tool call, not after the session expires. The options are a persistent profile, a seeded storage-state file, or an attached browser.

Playwright MCP vs CLI vs a data MCP server: which do you need?

Pick by the shape of the job: a browser MCP server for unknown flows, the CLI with skills for coding agents, a script for known repeats, and a data tool for public pages.

Option	Logs in, clicks, fills forms	Who decides each step	Fits
Playwright MCP	Yes	The agent	Unknown or exploratory flows
Playwright CLI with skills	Yes	The agent	Coding agent with filesystem access
Hosted data MCP server (Wayfern)	No	One call per task	Search, scrape, map, crawl
Plain Playwright script	Yes	Your code	Known flow that repeats

Microsoft’s Playwright MCP README states the CLI trade-off qualitatively: “If you are using a coding agent, you might benefit from using the CLI+SKILLS instead.” It publishes no numbers for that trade-off.

A data call can cost less than a click loop because one call returns page content or results. A browser loop pays one snapshot round trip per step and holds a browser open. In Microsoft’s example, each browser_type call comes back with a fresh snapshot of the page.

A research question shows the difference. A data MCP server answers it with a search call and a scrape call, and every tool result reports credits_charged. With Playwright MCP, the agent opens a search page, clicks a result and reads a snapshot after every step.

The honest catch: a data MCP server can’t log in, click or fill a form, so it doesn’t replace a browser. Wayfern’s server at https://api.wayfern.com/mcp has eleven tools, and its MCP docs cover the token scope and costs of each.

Our buyer’s guide to AI agent tools compares the two kinds of server.

Best for:

• Playwright MCP: flows you can’t script in advance, including logins.
• CLI with skills: coding agents that want to keep context small.
• Data MCP server: reading public pages.
• Script: flows you’ve already solved.

How do you point Playwright MCP at a remote browser?

Pointing Playwright MCP at a remote browser means passing the --cdp-endpoint flag, so the server attaches to a browser that is already running instead of launching its own. The config file’s remoteEndpoint is the documented counterpart.

Attach when the browser lives outside your machine: a hosted browser, one on another network, or one a separate process manages.

A CDP WebSocket is a WebSocket that carries Chrome DevTools Protocol messages, the protocol Playwright and Puppeteer use to drive Chromium.

This setup combines two documented interfaces (Playwright MCP’s --cdp-endpoint and Wayfern’s CDP WebSocket). Wayfern has no dedicated integration page for it.

1. Mint a link token under “Browser links” in your Wayfern project. Tokens have a connection cap and can be revoked.
2. Add the flag to the server entry. args must be a JSON array:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--cdp-endpoint",
        "wss://api.wayfern.com/ws?token=LINK_TOKEN"
      ]
    }
  }
}

3. Restart your client and ask for a page. Opening the socket starts the session, and the first message is a JSON connected message. Wayfern’s cold start is about 45 to 50 seconds, longer with a residential exit, so the agent’s first browser_navigate call waits that long.
4. Close the connection when the task ends. The MCP server didn’t launch this browser, so it won’t clean it up. A Wayfern instance is torn down when the last connection closes, and browser time is billed per open-page hour while a socket is open. Agent sessions can run for hours, so don’t leave one idle.

Keep the link token out of logs and shared config files. The URL is the credential.

	Local Playwright MCP	Wayfern over CDP
Browsers	chrome, firefox, webkit, msedge	Chromium only (linux-x64, headed on a virtual display)
Profile	Persistent by default	No customer-facing persistent profiles
Mobile layouts	--device emulation	Desktop device only

Local Playwright MCP supports chrome, firefox, webkit and msedge. As Wayfern’s anti-detect browser comparison states, Wayfern has no customer-facing persistent profiles, so your agent or code must save and restore storage between runs.

Use local Playwright MCP for mobile layouts and Firefox or WebKit checks. Use the hosted browser when a session must come from a chosen exit location. For the data-tool alternative, see our page on live web data for AI agents.

How do you limit what a browser agent can reach?

You limit what a browser agent can reach by keeping risky tools off, filtering origins, and treating everything the browser returns as untrusted input. Work through this checklist before you give an agent a live browser.

1. Leave browser_run_code_unsafe off. The Playwright MCP docs on playwright.dev flag this tool as equivalent to remote code execution. Don’t enable it for untrusted prompts or untrusted page content.

2. Treat WebMCP tools and content as untrusted. playwright.dev says the same of WebMCP: a page that publishes tools is still a page you don’t control. Read what a page’s tools do before you let the agent call them.

3. Treat everything the agent reads as input that can carry instructions. Snapshot text, console output and network output all come from the site, and a page can include text written to steer the agent. Keep credentials and unrelated tools out of any session that visits pages you don’t own.

4. Set --allowed-origins and --blocked-origins. The Playwright MCP options reference lists both flags for filtering which origins the browser may request. Allow only your target origin, and add egress rules at the network level so these flags are not your only control.

5. Set --allowed-hosts on the standalone HTTP server. This option belongs to the server you start with --port, and it limits which host names the server accepts. List only the host names your clients actually use.

6. Put a bearer-token check in front of --port. The Model Context Protocol specification has security and authorization guidance for HTTP transports. Follow it, and run the server behind a proxy that rejects requests without a valid bearer token.

7. Compare with a hosted data-tool server. Wayfern’s MCP server at https://api.wayfern.com/mcp authenticates with a scoped wf_ token (the mcp scope). That token can carry an expiry and can be revoked. Mint a token with only the mcp scope, set an expiry, and revoke it when the job ends.

What can you do when a site blocks the Playwright MCP browser?

When a site blocks the Playwright MCP browser, first work out what the site sees, then climb a short ladder of options that each change one thing. Detection is an arms race, so none of these steps is a guarantee.

A Playwright-launched browser is an automated browser. MDN says the navigator.webdriver property “indicates whether the user agent is controlled by automation”, so a page can read that signal directly.

Three Playwright MCP flags change less than they appear to:

• --proxy-server changes the network exit: the IP address the site sees.
• --user-agent changes the declared user agent string, the text the browser reports about itself.
• --device applies emulation for a named device, per the Playwright MCP options reference.

None of them changes the browser identity as a whole. A different exit or user agent string leaves the automation signals in place.

Work down this ladder in order:

1. Check permission first. Read the site’s terms and robots rules, and look for an official API or feed. Use only lawful, public-data, testing, research or monitoring jobs.
2. Use a data call for public pages. If you only need the content, Wayfern’s scrape_page or search_web tools over the Wayfern MCP server replace a click loop with one request. With proxy: "auto", the Web Data API starts on a datacenter exit and retries on residential when blocked.
3. Use a hosted browser if you need a session. Wayfern’s default is a datacenter exit. You can choose a residential exit by country, region, city or isp, or add a sticky session id to hold one residential IP for a flow. See anti-detect browser sessions over CDP.

Check your location codes. An unknown location is refused with close code 4007 and never falls back to another exit, so a typo fails loudly.

Each option changes where requests come from or how the browser presents itself. None of them promises a page will load.

Frequently asked questions

How do I run Playwright MCP against a remote browser?

To run Playwright MCP against a remote browser, pass the browser’s CDP WebSocket URL with --cdp-endpoint. The server attaches to that browser instead of launching one. It didn’t start the browser, so whoever owns the connection must close it when the task ends.

Does Playwright MCP need a vision model?

Playwright MCP works without a vision model, according to the Playwright MCP getting-started guide. It gives the model structured accessibility snapshots instead of screenshots, so a text-only model can read the page and pick elements by ref.

What Node.js version does Playwright MCP need?

Playwright MCP needs Node.js, and the Playwright docs list it under prerequisites. The exact minimum is the engines field in the package’s package.json. Read that field, then compare it with the output of node --version.

Does Playwright MCP keep me logged in between runs?

By default it does. The server uses a persistent profile on disk, so cookies and logins survive a restart. With --isolated, the profile lives in memory and the state is gone when the session closes.

Can I use Playwright MCP over HTTP instead of stdio?

Start the server with --port and it runs as a standalone HTTP server instead of a stdio child process. Point your client at that URL. Bind it to localhost, because anyone who can reach the port can drive your browser.

Next steps for your agent’s browser

Today: Add the server to your MCP client with a valid args array (npx as the command, ["@playwright/mcp@latest"] as the arguments). Then check the Node.js minimum in the Playwright MCP prerequisites before you debug anything else.

This week:

• Decide where login state lives: the default persistent profile, --isolated, or a storage state file.
• Set an idle timeout and an origin allowlist with --allowed-origins.
• Keep browser_run_code_unsafe off.

Before production: If your agent mostly needs public page data, try Wayfern’s MCP server at https://api.wayfern.com/mcp. It has 11 tools on one credit balance and takes an mcp-scoped wf_ token.

If the agent needs a browser in a chosen location, pass the Wayfern CDP WebSocket to --cdp-endpoint and close the socket yourself when the task ends. Check Wayfern’s credit rates before you leave a session running.

Re-read the Playwright MCP options reference every time you upgrade.

To test the hosted path, follow the Wayfern docs to get a wf_ token and connect your agent.

Sources

GitHub - microsoft/playwright-mcp: Playwright MCP server · Playwright MCP | Playwright · Playwright MCP · Developer Docs - Browser, Web Data API & MCP | Wayfern · microsoft__playwright-mcp - GitHub · MCP Server for AI Agents | Wayfern Docs · Anti-Detect Browser Sessions over CDP | Wayfern · Pricing | Wayfern. Every other source is linked where the article cites it.