Repository navigation
playwright mcp best practices
A browser MCP server is unusual among developer tools in that the same setup can be excellent or unusable depending on four decisions, none of which is a code change. These are those four, then the habits that follow from them.
Every tool the server exposes has a description, and every description is in the model's context on every turn. A browsing session is dozens of turns. This is the single largest avoidable cost in the category.
Measured on our own server, because we can read our own source and nobody publishes this number: 17 tools whose complete definitions are 3,497 tokens, sent again on every single turn (9,207 characters of description plus each tool's argument schema, enumerated from the server's own registry on 2026-10-12 and counted with a tokenizer). A forty-turn session therefore spends on the order of 128,000 tokens restating what the tools are, before a single page has been read. That is the budget the next two paragraphs are about.
Microsoft's server makes capabilities additive with --caps, so vision, pdf and
devtools are off unless you ask. Leave them off until a page forces the issue.
Do not register two browser servers side by side for coverage: the overlapping
tool names cost context twice and make the model's choice worse, which is the
part people do not predict.
Three options, and picking by accident is how people end up in browser is already in use.
Isolated (--isolated): a throwaway profile per session. Right default for
exploration. Two clients can run at once. You start logged out every time.
Persistent (--user-data-dir): the browser remembers. Right when the flow
needs a login you do not want to redo. One live browser per directory, so give
each client its own path.
Storage state (--storage-state): a saved cookie and local-storage
snapshot, loaded into an otherwise clean profile. The middle option people
forget, and usually the best one: logged in, no shared lock, no accumulated
history.
The failure that wastes the most tokens is not a wrong click, it is a model that does not know when it is finished. "Find the pricing page" ends. "Look around the site" does not.
Two habits that pay immediately:
- Name the end state. "Open the pricing page and tell me the price of the team plan" beats "check their pricing", because the second one invites five more page loads after the answer was already on screen.
- Say what to do when it is not there. Without that, a model that cannot find the thing will keep looking, and looking is the expensive part.
This is the practice most worth internalising, and it is the one nobody puts in a best-practices list because it argues against the tool.
An MCP session is a good way to discover a flow: you did not know the page's shape, and the model worked it out. It is a bad way to repeat one. On the second run the model rediscovers the same steps and you pay again, more slowly and less reproducibly than the script it should have become.
Use the session to find the selectors and the order, then write those down as ordinary code. Playwright MCP vs the CLI has the split in full, and MCP for web scraping applies it to the case where the repetition is the whole job.
Read the page before acting on it. A snapshot costs one turn and saves several failed clicks. Models that click first tend to click something that moved.
Prefer a reference the server gave you over a selector you invented. The accessibility snapshot returns stable references precisely so the next call does not have to guess.
Close what you open. Tabs accumulate, each one holds memory, and a session that has been alive for an hour is usually carrying five pages nobody is reading.
Keep one browser per concern. If you are comparing two sites, two named browsers is clearer to the model than one browser with two tabs, and much clearer when something fails.
Check the boring causes before blaming the server. Slow is usually the model's round trips, not the browser. Not found is often a page that renders after the snapshot was taken. And a challenge page is a network and pacing question far more often than a browser question: why an agent gets blocked.
invisible_playwright_mcp makes two of these decisions structural rather than optional. A server is one identity for its whole life, so practice 2 has no shared profile to get wrong. Identity is derived from a seed, so a session that failed can be replayed as the same browser, which turns "it worked yesterday" into something you can test.
The cost is that a second identity is a second registered server rather than an argument, and the engine covers Windows and Linux only. The MCP server has the configuration.
How do I make Playwright MCP cheaper? Fewer capabilities, one server, a stopping condition in the instruction, and stop using it for flows you already know.
Should I use isolated or persistent? Isolated for exploring, storage state for logged-in flows, persistent only when you genuinely want accumulated history.
Why is it so slow? Each step is a round trip through a model. That is the design, not a defect. If speed matters, the flow belongs in code.
How many tools should a browser MCP server have? Enough to read state, to reach what selectors cannot, and to fall back to JavaScript. How the tools are shaped argues the case.
Can I use it on a site I have to log into? Yes. Whether you should is a separate question: should you log your agent into accounts.
See also: Playwright MCP vs the CLI, Playwright MCP with a proxy, and writing tasks for a browser agent.
-
microsoft/playwright-mcp, retrieved 2026-09-10, for
--caps,--isolated,--user-data-dirand--storage-state.
Written while maintaining a competing server. Practice 4 argues against using either of them for the repeat case, which is the recommendation we would least like to make and the one that saves the most money.
- OpenAI Operator alternatives
- Open-source Operator-style agents
- Is OpenAI Operator still available?
- OpenAI Operator vs Claude computer use
- browser-use alternatives
- Choosing an AI browser agent
- Open-source AI browser agents
- Open-source computer-use agents
- What is an AI web agent?
- AI browser agents vs traditional scraping
- Cloud browser infrastructure for AI agents, explained
- Browserbase alternatives
- Firecrawl vs an AI browser agent
- Skyvern alternatives
- Stagehand vs browser-use
- Project Mariner is gone: what replaced it
- Manus alternatives
- Gemini computer use vs Claude computer use
- A stealth browser MCP, reviewed honestly by its own wiki
- AI browser vs AI browser agent: which one do you want?
- AI browser agent vs RPA: which one fits the job
- AI browser agent vs n8n, Zapier and Make
- Vercel agent-browser alternatives, compared honestly
- What is an agentic browser? Definition and the two kinds
- Open-source agentic browsers: the three layers, compared
- Choosing an MCP server for browser automation: four axes
- Stealth MCP servers compared: Camoufox, nodriver, Patchright
- Playwright MCP alternatives, and the three you don't need
- Autonomous browser agents: the four rungs of autonomy
- What is actually free in the AI browser agent stack
- browser-use on GitHub: what the repo actually gives you
- Playwright MCP vs Chrome DevTools MCP: different jobs
- How to choose among MCP servers: a map by category
- Which MCP servers are worth adding to Claude Code
- MCP on GitHub: finding servers and judging them fast
- MCP vs an API: the decision, and what the wrapper costs
- MCP alternatives: when the protocol is the wrong shape
- Why does my AI agent get blocked?
- The timing signal AI agents give off
- Agent retry loops trip rate limits, not fingerprints
- Claude computer use detected as a bot
- browser-use getting blocked: what you can and cannot change
- Playwright MCP session blocked: four causes, four fixes
- Playwright MCP and captchas: what actually gets you past
- Cloudflare and a browser MCP server: what is being read
- Can an AI agent solve a captcha? The honest answer
- Getting an AI agent to fill out forms
- The best model for an MCP browser agent, and what it really costs
- Browser problem or model problem?
- How to use a Playwright MCP server with Claude Code
- Extracting data to a CSV with an AI agent
- Monitoring a page for changes with an AI agent
- How to let Claude Desktop control a browser
- How to add a browser to Cursor as an MCP server
- Using an AI agent to hunt for apartments
- Getting website data into Google Sheets with an AI agent
- Using an AI agent to download invoices from portals
- AI agents for web research
- Using an AI agent to test your own website
- How to add a browser to Cline as an MCP server
- Posting to social media with an AI agent
- Posting to Facebook with an AI agent
- Posting to Instagram with an AI agent
- Posting to X with an AI agent
- Automating LinkedIn posts: read this first
- Appointment bots: what they are and what an agent can legitimately do
- Track prices across sites with an AI agent
- Build a lead list with an AI browser agent
- Run an AI browser agent on a schedule
- AI browser agent with a local LLM: what changes
- Should you log your AI agent into your accounts?
- How to write a task an AI browser agent can follow
- Move data between two web apps with an AI agent
- The MCP server
- How the tools are shaped, and why
- Playwright MCP vs the Playwright CLI: which fits when
- Playwright MCP: browser is already in use, and the fix
- Playwright MCP best practices: four decisions that matter
- Playwright MCP with a proxy, and the three leaks it leaves
- A browser MCP server in GitHub Copilot: setup and limits
- Using a browser MCP server for web scraping: the pattern
- Which LLM for browser automation: the four properties
- How to build a browser agent, and what to take instead
- Getting an AI agent to log into a website: three routes
- MCP tools, resources and prompts: who controls each
- How many MCP tools is too many? The context arithmetic
- How to build an MCP server: the decisions, not the scaffold
- Local or remote MCP server: what changes, and what does not
- Writing an MCP client in Python: the thirty-line version
- Self-hosted AI agent: what one actually costs to run
- How long an AI browser agent takes per step, measured
- Text, HTML, snapshot or screenshot: what the agent should read
- Giving an AI browser agent a stopping condition
- Keeping an AI browser agent out of destructive actions
- Why did the AI agent click the wrong thing
- When the page changes under the AI agent
- Running one AI agent task across a list of sites
- Seeing a page as it appears in another country
- Getting data out of a dashboard with no export button
- Two browsers in one session: main and support
- Finding the dead links on a site with an AI agent
- Filling a CRM record from a company's website
- One form submission per spreadsheet row, with an AI agent
- Dated screenshots of a page as evidence
- Checking order and delivery status with an AI agent
- Reading a PDF that opens inside the browser
- Summarising a long page or thread with an AI agent
- Collecting every image on a page with its caption
- Collecting event and course listings with an AI agent
- Cancelling a subscription with an AI agent
- What an AI agent can and cannot do inside an iframe
- Shadow DOM and an AI agent: you can click it, you cannot read it
- How to add a browser to Codex as an MCP server
- What a page snapshot costs, per control
- How to let Gemini CLI use a browser
- Native selects and the ones that only look like selects
- Clicking by selector or by coordinates
- How long the agent waits before it gives up
- What a second browser costs
- Uploading a file with an AI agent, and why this one cannot
- Watching the agent work, and when it is worth it
- When not to use an AI browser agent
- Agent or script: deciding once instead of every time
- Using the keyboard instead of the mouse
- Secrets in an agent task: where they end up
- What an agent run should log
- Deduplicating what an AI agent collects
- Normalising values across sites
- Validating an AI agent's output
- Reading a table with an AI agent
- Driving a site's own search and filters
- The task works headed and fails headless
- How to let the AdaL CLI use a browser