     [Blog](https://scrapfly.io/blog)   /  [ai](https://scrapfly.io/blog/tag/ai)   /  [Playwright MCP on Protected Sites: Connect It to a Remote Stealth Browser](https://scrapfly.io/blog/posts/playwright-mcp)   

# Playwright MCP on Protected Sites: Connect It to a Remote Stealth Browser

 by [Mohab Yousry](https://scrapfly.io/blog/author/mohab-yousry-9396552a) Nov 18, 2026 14 min read [\#ai](https://scrapfly.io/blog/tag/ai) [\#cloud-browser](https://scrapfly.io/blog/tag/cloud-browser) [\#playwright](https://scrapfly.io/blog/tag/playwright) 

 [  ](https://www.linkedin.com/sharing/share-offsite/?url=https%3A%2F%2Fscrapfly.io%2Fblog%2Fposts%2Fplaywright-mcp "Share on LinkedIn") [  ](https://x.com/intent/tweet?url=https%3A%2F%2Fscrapfly.io%2Fblog%2Fposts%2Fplaywright-mcp&text=Playwright%20MCP%20on%20Protected%20Sites%3A%20Connect%20It%20to%20a%20Remote%20Stealth%20Browser "Share on X") [  ](https://www.facebook.com/sharer/sharer.php?u=https%3A%2F%2Fscrapfly.io%2Fblog%2Fposts%2Fplaywright-mcp "Share on Facebook")    

 

 

Summarize this article with

 [  ](https://chat.openai.com/?q=Summarize%20this%20article%20and%20explain%20how%20Scrapfly%20helps%20me%20scrape%20any%20website%20at%20scale%20and%20bypass%20anti-bot%20systems%20for%20my%20use%20case%3A%20https%3A%2F%2Fscrapfly.io%2Fblog%2Fposts%2Fplaywright-mcp) [  ](https://claude.ai/new?q=Summarize%20this%20article%20and%20explain%20how%20Scrapfly%20helps%20me%20scrape%20any%20website%20at%20scale%20and%20bypass%20anti-bot%20systems%20for%20my%20use%20case%3A%20https%3A%2F%2Fscrapfly.io%2Fblog%2Fposts%2Fplaywright-mcp) [  ](https://x.com/i/grok?text=Summarize%20this%20article%20and%20explain%20how%20Scrapfly%20helps%20me%20scrape%20any%20website%20at%20scale%20and%20bypass%20anti-bot%20systems%20for%20my%20use%20case%3A%20https%3A%2F%2Fscrapfly.io%2Fblog%2Fposts%2Fplaywright-mcp) [  ](https://www.perplexity.ai/search/new?q=Summarize%20this%20article%20and%20explain%20how%20Scrapfly%20helps%20me%20scrape%20any%20website%20at%20scale%20and%20bypass%20anti-bot%20systems%20for%20my%20use%20case%3A%20https%3A%2F%2Fscrapfly.io%2Fblog%2Fposts%2Fplaywright-mcp) [  ](https://www.google.com/search?udm=50&aep=11&q=Summarize%20this%20article%20and%20explain%20how%20Scrapfly%20helps%20me%20scrape%20any%20website%20at%20scale%20and%20bypass%20anti-bot%20systems%20for%20my%20use%20case%3A%20https%3A%2F%2Fscrapfly.io%2Fblog%2Fposts%2Fplaywright-mcp) 



         

I asked an agent to get the prices from a certain page and it returned nothing. I went through the requests and found that every `browser_navigate` call has succeeded, so what is the problem? A challenge page and Playwright MCP didn't flag it.

Below we will go through setting up Playwright MCP, why a local browser gets caught and how to use a remote browser instead.



## Key Takeaways

Blocking in Playwright MCP is a common issue. It can be caused by the local browser leaking our IP address, OS and timezone, and it's often missed as the agent reads the challenge page as a successful tool call. To avoid getting blocked we can:

- Check the page content ourselves instead of relying on the tool call status
- Stay away from headless mode as it adds `HeadlessChrome` to the user agent
- Connect to a remote browser over CDP and keep the default mode, since `--isolated`, `--device` and `--mobile` won't work there
- Navigate to the page again after a long pause as remote sessions can expire without any warning
- [Scrapfly Cloud Browser](https://scrapfly.io/products/cloud-browser-api) only needs the `--cdp-endpoint` flag and the OS, country and proxy pool are set in the connection URL.

**Get web scraping tips in your inbox**Trusted by 100K+ developers and 30K+ enterprises. Unsubscribe anytime.







## What Is Playwright MCP and How Does It Control a Browser?

Playwright MCP is Microsoft's MCP server for browsers. You can use it with an AI agent to make it open pages or interact with a web page in general. It only needs you to add the `@playwright/mcp` package to your client then the agent gets a handful of browser tools that make the interactions.

After every action it gets back an accessibility snapshot, a document where every button and link has a short reference attached. The agent reads the page and uses that reference to make the interactions.

New to MCP itself? See

[What Is MCP? Understanding the Model Context ProtocolWhat is MCP? Learn how the Model Context Protocol powers tools like Copilot Studio by giving AI models access to real-time, structured context.](https://scrapfly.io/blog/posts/what-is-mcp-understanding-the-model-context-protocol)

Every tool call follows the same three steps:



Say the agent opens `https://web-scraping.dev/products` returning:



```
link "Box of Chocolate Candy" [ref=e43]
link "Dark Red Energy Potion" [ref=e52]
```



To open the first product, it just passes `e43` to the click tool and Playwright handles the rest.

One thing worth knowing early is where that browser lives. By default it launches right on your machine, in a visible window. Keep that in mind, because it's exactly what gets you blocked later on.

There are plenty more tools than the few mentioned here, and the [Playwright MCP README](https://github.com/microsoft/playwright-mcp) lists every one of them. And if you'd like to see what else is out there besides Playwright MCP, we've compared the options here:

[5 MCP Servers for Web Scraping and Browser Automation in 2026Compare five MCP servers by the work they can actually do: protected-site scraping, browser control, debugging, static fetching, and cross-browser automation.](https://scrapfly.io/blog/posts/best-mcp-servers-for-web-scraping)



## How Do You Set Up Playwright MCP in Claude Code, Cursor, and Claude Desktop?

By using `npx @playwright/mcp@latest` for all of them. The only thing that changes is where you register it. Playwright MCP is a stdio server, so the client starts and stops the process and you do not have to intervene.

We will need different setups for different agents. For Claude Desktop and Cursor, here is the standard config file example:



json

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



If you're using Claude Desktop put it in `claude_desktop_config.json` and restart the app. For Cursor open Settings, then MCP, and add a new server with the same content.

For Claude Code you will need only this line:



bash

```bash
claude mcp add playwright npx @playwright/mcp@latest
```



Now test it with a prompt like:



```
Open https://web-scraping.dev/products and list the product names.
```



If it returned the five product names on that site then it is working fine.

You will find other agents install instructions in the [README](https://github.com/microsoft/playwright-mcp). If you would rather write a script than prompt an agent, see

[Web Scraping With Playwright in 2026: A Python GuideScrape JavaScript-rendered pages with Playwright and Python in 2026: locators, waiting, request interception, resource blocking, and concurrency.](https://scrapfly.io/blog/posts/web-scraping-with-playwright-and-python)

Now you have a working setup, but what if you are targeting a protected site.



## Why Does Playwright MCP Get Blocked on Protected Sites?

It runs locally, so the browser shows your IP, OS and timezone, and if you also run it headless, the user agent says `HeadlessChrome`.

When testing to see what actually happens, I noticed that headless mode is spotted easily and also that you're using your machine. You might think that `navigator.webdriver` exposes you too, but no it is not the issue here. Whether you got the page results or not, as long as you got a reply, it returns as a success.



You can use `--user-agent`, `--proxy-server` and `--init-script` flags to try and fix these issues, but each one patches a single signal and you end up chasing leaks. If you want to go this way, see

[Playwright Stealth: Bypass Bot Detection in Python &amp; Node.jsComplete guide to using playwright-stealth in Python and playwright-extra with stealth plugin in Node.js. Covers how detection works, evasion module breakdown, testing, limitations, and scaling to production with cloud browsers.](https://scrapfly.io/blog/posts/playwright-stealth-bypass-bot-detection)

Also give this guide a look it explains what these checks actually look at.

[How to Bypass Cloudflare When Web Scraping in 2026Cloudflare offers one of the most popular anti scraping service, so in this article we'll take a look how it works and how to bypass it.](https://scrapfly.io/blog/posts/how-to-bypass-cloudflare-anti-scraping)

Running the browser somewhere else saves you a lot though and does not need any changes in your pipeline, you attach Playwright MCP to it and it takes one flag to do so.



## How Do You Connect Playwright MCP to a Remote Browser With --cdp-endpoint?

Currently, there are two popular browser automation protocols:

- The older webdriver protocol which is implemented through an extra browser layer called webdriver. Webdriver intercepts action requests and issues browser control commands.
- The newer Chrome DevTools Protocol (CDP for short). Unlike webdriver, the CDP control layer is built into Chromium-based browsers like Chrome and Edge.

### Point Playwright MCP at Scrapfly Cloud Browser

Let's take a quick look at how we can point Playwright MCP at Scrapfly Cloud Browser. We'll take the setup section config and add `--cdp-endpoint` with the Cloud Browser WebSocket URL:



json

```json
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--cdp-endpoint",
        "wss://browser.scrapfly.io?key=YOUR_SCRAPFLY_KEY&proxy_pool=public_datacenter_pool&os=windows&country=us"
      ]
    }
  }
}
```



That's the whole change.

Let's try this out by opening `https://web-scraping.dev/products` and listing the product names.

If it returned the five product names on that site then it is working fine.

Here are the results we got. The first `browser_navigate` took 4.6 to 4.8 seconds including starting the remote browser:

`browser_snapshot` listed all five products. `browser_evaluate` came back as Windows Chrome 156, platform `Win32`, `webdriver: false` and a US timezone. None of that is our test machine.

We can also see additional variables in the connection URL, let's go over them:

- **os**: the operating system fingerprint; `android`, `iphone` and `ipad` pick a whole mobile device persona
- **country**: the proxy location along with a matching timezone and locale
- **proxy\_pool**: datacenter or residential IPs

For the other parameters, refer to the [Cloud Browser parameter table](https://scrapfly.io/docs/cloud-browser-api/getting-started) and the [proxy pools docs](https://scrapfly.io/docs/cloud-browser-api/proxy).



### How Do You Keep the API Key Out of Shared MCP Configs?

For Claude desktop and Cursor it's the same config as above, but add the URL in an env rather than in the args directly.



json

```json
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"],
      "env": {
        "PLAYWRIGHT_MCP_CDP_ENDPOINT": "wss://browser.scrapfly.io?key=YOUR_SCRAPFLY_KEY&proxy_pool=public_datacenter_pool&os=windows&country=us"
      }
    }
  }
}
```



If you're using Claude Desktop put it in `claude_desktop_config.json` and restart the app. For Cursor open Settings, then MCP, and add a new server with the same content.

For Claude Code you will need only this line:



bash

```bash
claude mcp add playwright -e PLAYWRIGHT_MCP_CDP_ENDPOINT="wss://browser.scrapfly.io?key=$SCRAPFLY_API_KEY&proxy_pool=public_datacenter_pool&os=windows&country=us" \
  -- npx @playwright/mcp@latest
```



This keeps the key out of the config you share. Claude Code saves it in `~/.claude.json`, which doesn't get committed, unlike a project's `.mcp.json`, so never store credentials there. You'll find these details at [Claude Code MCP docs](https://code.claude.com/docs/en/mcp).

### Which Playwright MCP Flags Break Over CDP?

| Flag | Over CDP on Cloud Browser | Use instead |
|---|---|---|
| `--isolated` | Page tools fail | Default mode |
| `--device`, `--mobile` | Refused at startup | `os=android`, `iphone` or `ipad` in the URL |
| `--headless`, `--browser`, `--executable-path` | Ignored, nothing is launched | Remote browser settings |
| `--user-agent`, `--viewport-size` | Not applied to the attached browser | `os` in the URL |
| `--proxy-server` | Not applied to the attached browser | `proxy_pool` and `country` |

The `--isolated` flag asks for a fresh in-memory browser context, and Cloud Browser runs one browser context per session, so every page tool fails with a `Protocol error (Target.createTarget)` telling you to use the existing context. You don't need the flag anyway, as each connection without a `session` parameter already gets its own fresh browser. `--device` and `--mobile` try to emulate a mobile device, you can do that by passing `os=` in the cloud browser URL and add the OS you want.

`--headless`, `--browser` and `--executable-path` indicate how would you want to launch a browser, so you can manage that from the cloud browser settings. `--proxy-server` also won't work as the cloud browser has its own network settings now, you can manage that with `proxy_pool` and `country`.

Now that we have a remote browser attached, let's look at what happens to the session during a long agent run.



Scrapfly

#### Need a cloud browser for scraping?

Run headless browsers at scale with Scrapfly Cloud Browser — no infrastructure to manage.

[Try Free →](https://scrapfly.io/register)

## What Happens to the Remote Browser During a Long Agent Session?

The session is kept live according to session `timeout` which is by default `900s` and can get up to `1800s`, then the session is closed and when you make a new call it opens a new one.

To understand the flow, here is a diagram for you.



Here is a thread on reddit, with developers facing the same problem saying that "[each agent step seems to start a new session](https://www.reddit.com/r/LLMDevs/comments/1lh0769/anyone_using_playwright_mcp_with_agentic_ai/)". That's what it seems when the remote session keeps closing between steps.

You can manage that by raising the session timeout in the endpoint URL.



json

```json
"wss://browser.scrapfly.io?key=YOUR_SCRAPFLY_KEY&proxy_pool=public_datacenter_pool&os=windows&country=us&timeout=1800"
```



Also add an idle timeout in milliseconds to `args` to avoid paying for the idle time.



json

```json
"args": ["@playwright/mcp@latest", "--idle-timeout=300000"]

```



It saves you paying the idle time, but keep in mind that you lose the open page when it disconnects. Try prompting your agent to navigate again after long pauses like:



```
After a long pause, navigate to the page again before trusting a snapshot.
```



## How Do You Get Playwright MCP Past a Challenge on the First Page?

Playwright MCP can't help with that. There are two ways to do so and both come before the MCP. The faster one is editing the URL to add a captcha solver. You can also start the session by the cloud browser unblock API then hand it to Playwright MCP.

I'll show you both ways, but keep in mind that the website I'm testing on, `web-scraping.dev`, only shows that the setup is working. It is not protected, so it does not guarantee anything.

### Using Residential Proxies and the Captcha Solver

This is the faster, easier approach we talked about earlier. Here is an example:



json

```json
"PLAYWRIGHT_MCP_CDP_ENDPOINT": "wss://browser.scrapfly.io?key=YOUR_SCRAPFLY_KEY&proxy_pool=public_residential_pool&os=windows&country=us&target_url=https%3A%2F%2Fweb-scraping.dev%2Fproducts&solve_captcha=true"
```



The parameters added here help pass the challenge, like `public_residential_pool` which uses residential IPs and `solve_captcha=true` that uses a captcha solver and according to [Captcha Solver docs](https://scrapfly.io/docs/cloud-browser-api/captcha-solver) it only bills on success too.

### Start Playwright MCP From an Unblocked Session

A safer solution, though it takes more steps, is clearing the check before even using the MCP with the [Unblock API](https://scrapfly.io/docs/cloud-browser-api/unblock) and then hand the session to Playwright MCP.

Let's see how:



bash

```bash
set -euo pipefail
WS=$(curl --max-time 120 -fsS -X POST "https://browser.scrapfly.io/unblock?key=$SCRAPFLY_API_KEY" \
  -H "Content-Type: application/json" -d "{\"url\": \"$1\", \"country\": \"us\"}" | jq -er .ws_url)
PLAYWRIGHT_MCP_CDP_ENDPOINT="$WS" exec npx -y @playwright/mcp@latest
```



Save it as `playwright-mcp-unblock.sh`, then use it as a server.



json

```json
{
  "mcpServers": {
    "playwright": {
      "command": "/path/to/playwright-mcp-unblock.sh",
      "args": ["https://web-scraping.dev/products"],
      "env": { "SCRAPFLY_API_KEY": "YOUR_SCRAPFLY_KEY" }
    }
  }
}
```



## When Should an Agent Skip the Browser and Fetch Pages Through an MCP Tool?

Sometimes you only need to read a page. You don't need to click or type, so using a browser is not necessary. Choosing a scraping tool would be better for this use case as it does not have a session to expire.

| Route | Browser runs | Gets through blocks with | Fits when |
|---|---|---|---|
| Playwright MCP, local | Your machine | Nothing built in | Unprotected sites, local apps |
| Playwright MCP + Cloud Browser | Scrapfly, over CDP | Scrapium fingerprint, proxy pool | Clicks, forms, multi-step flows |
| Unblock launcher + Playwright MCP | Scrapfly, over CDP | Unblock API on the first page | Protected first page, then interaction |
| Scrapfly MCP Server | No browser to manage | Unblocker (previously ASP) | Reading pages, no interaction |

If this is your case, go with [Scrapfly MCP Server](https://scrapfly.io/docs/mcp/getting-started). This is how to use it in Claude code:



bash

```bash
claude mcp add --transport http scrapfly https://mcp.scrapfly.io/mcp -H "Authorization: Bearer $SCRAPFLY_API_KEY"
```



This server also offers a cloud browser connection, so it might be even more helpful to you depending on your use case. There are other options too, like [native Browser MCP endpoint](https://scrapfly.io/docs/cloud-browser-api/mcp) and more you can find in this guide here:

[5 MCP Servers for Web Scraping and Browser Automation in 2026Compare five MCP servers by the work they can actually do: protected-site scraping, browser control, debugging, static fetching, and cross-browser automation.](https://scrapfly.io/blog/posts/best-mcp-servers-for-web-scraping)



## FAQ

Should you use Playwright CLI or Playwright MCP? 

Use Playwright CLI to save tokens, as it keeps tool schemas and accessibility trees out of the model's context, as stated in the [README](https://github.com/microsoft/playwright-mcp). Go with the MCP for long agent loops that keep browser state.







Can Playwright MCP use your logged-in Chrome?

Yes, it can, but you need to install the Playwright Extension for Chrome and run Playwright MCP with `--extension`. See the [browser connection docs](https://playwright.dev/mcp/configuration/browser-extension) for more about this.







Does Playwright MCP run headless by default?

No, it does not. You need to add `--headless` in order to use it that way.







Is Playwright MCP free to use?

Yes, it's open source under the Apache-2.0 license.









## Conclusion

Going with a remote browser instead of your own removes the leaks a local browser shows, and a cloud browser like [Scrapfly Cloud Browser](https://scrapfly.io/products/cloud-browser-api) also sets the OS, country and proxy pool from the connection URL.

If all you need is to read the text of a page without any interaction, then you probably don't need a browser at all, and [Scrapfly MCP Server](https://scrapfly.io/docs/mcp/getting-started) will be the way to go.



### Power your scraping with Scrapfly

Forget about getting blocked. Scrapfly handles anti-bot bypasses, browser rendering, and proxy rotation so you can focus on the data.



[Try for FREE!](https://scrapfly.io/register)



Legal Disclaimer and Precautions

This tutorial covers popular web scraping techniques for education. Interacting with public servers requires diligence and respect:

- Do not scrape at rates that could damage the website.
- Do not scrape data that's not available publicly.
- Do not store PII of EU citizens protected by GDPR.
- Do not repurpose *entire* public datasets which can be illegal in some countries.

Scrapfly does not offer legal advice but these are good general rules to follow. For more you should consult a lawyer.

 

   [  Add as a preferred source ](https://google.com/preferences/source?q=scrapfly.io) Table of Contents















 

  Table of Contents

- [Key Takeaways](#key-takeaways)
- [What Is Playwright MCP and How Does It Control a Browser?](#what-is-playwright-mcp-and-how-does-it-control-a-browser)
- [How Do You Set Up Playwright MCP in Claude Code, Cursor, and Claude Desktop?](#how-do-you-set-up-playwright-mcp-in-claude-code-cursor-and-claude-desktop)
- [Why Does Playwright MCP Get Blocked on Protected Sites?](#why-does-playwright-mcp-get-blocked-on-protected-sites)
- [How Do You Connect Playwright MCP to a Remote Browser With --cdp-endpoint?](#how-do-you-connect-playwright-mcp-to-a-remote-browser-with-cdp-endpoint)
- [Point Playwright MCP at Scrapfly Cloud Browser](#point-playwright-mcp-at-scrapfly-cloud-browser)
- [How Do You Keep the API Key Out of Shared MCP Configs?](#how-do-you-keep-the-api-key-out-of-shared-mcp-configs)
- [Which Playwright MCP Flags Break Over CDP?](#which-playwright-mcp-flags-break-over-cdp)
- [What Happens to the Remote Browser During a Long Agent Session?](#what-happens-to-the-remote-browser-during-a-long-agent-session)
- [How Do You Get Playwright MCP Past a Challenge on the First Page?](#how-do-you-get-playwright-mcp-past-a-challenge-on-the-first-page)
- [Using Residential Proxies and the Captcha Solver](#using-residential-proxies-and-the-captcha-solver)
- [Start Playwright MCP From an Unblocked Session](#start-playwright-mcp-from-an-unblocked-session)
- [When Should an Agent Skip the Browser and Fetch Pages Through an MCP Tool?](#when-should-an-agent-skip-the-browser-and-fetch-pages-through-an-mcp-tool)
- [FAQ](#faq)
- [Conclusion](#conclusion)
 
    Join the Newsletter  Get monthly web scraping insights 

 

  



Scale Your Web Scraping

Anti-bot bypass, browser rendering, and rotating proxies, all in one API. Start with 1,000 free credits.

  No credit card required  1,000 free API credits  Anti-bot bypass included 

 [Start Free](https://scrapfly.io/register) [View Docs](https://scrapfly.io/docs/onboarding) 

 Not ready? [Get our newsletter](#newsletter-modal) instead. 

 

 

## Related Articles

 [     

 blocking playwright 

### Is Chrome CDP Detectable? CDP vs WebDriver for Browser Automation

Chrome CDP is not stealth by itself. Learn how CDP, WebDriver, Playwright, Puppeteer, nodriver, Camoufox, and cloud brow...

 

 ](https://scrapfly.io/blog/posts/chrome-cdp-stealth-browser-automation-detection-explained) [     

 ai tools 

### 5 MCP Servers for Web Scraping and Browser Automation in 2026

Compare five MCP servers by the work they can actually do: protected-site scraping, browser control, debugging, static f...

 

 ](https://scrapfly.io/blog/posts/best-mcp-servers-for-web-scraping) [     

 headless-browser proxies 

### Camoufox for Web Scraping: Setup, Proxies and Servers

A tested guide to running Camoufox for web scraping: Python setup, proxy and GeoIP configuration, remote servers, known ...

 

 ](https://scrapfly.io/blog/posts/camoufox-for-web-scraping) 

  

## Related Questions

- [ Q How to Use cURL Config Files? ](https://scrapfly.io/blog/answers/how-to-set-curl-config-file)
- [ Q How to save and load cookies in Python requests? ](https://scrapfly.io/blog/answers/save-and-load-cookies-in-requests-python)
- [ Q How to save and load cookies in Playwright? ](https://scrapfly.io/blog/answers/how-to-save-and-load-cookies-in-playwright)
- [ Q How To Send Multiple cURL Requests in Parallel? ](https://scrapfly.io/blog/answers/how-to-send-multiple-curl-requests-in-parallel)
 
  



   



 Run headless browsers at scale, **1,000 free credits** [Start Free](https://scrapfly.io/register)