Connect Playwright MCP to a cloud browser by giving the MCP server the browser provider’s Chromium CDP endpoint. Install and run @playwright/mcp from an MCP client with Node.js 20 or newer, then pass the provider’s exact endpoint and any required authentication headers. The endpoint is provider-specific: copy it from that service’s dashboard or documentation rather than guessing. If the provider supplies a remote Playwright endpoint instead of CDP, use --endpoint.
What you need before connecting
- A compatible MCP client: for example, VS Code, Cursor, Windsurf, Claude Code, Claude Desktop, or another client that supports MCP servers.
- Node.js 20 or newer: the configuration below launches the server with
npx. - An active cloud-browser session: create one with your provider before connecting. You need its Chromium CDP URL, and possibly an authentication token or header.
- Network reachability: the computer or worker running Playwright MCP must be able to reach the provider endpoint.
The CDP URL and credentials are secrets. Keep them out of prompts, source control, screenshots, and logs. Use the provider’s recommended secret or environment-variable mechanism where available.
Connect Playwright MCP to a cloud browser
- Create a browser session. In your cloud-browser provider’s dashboard or API, start a Chromium session and copy its CDP endpoint. Verify whether access requires a token, a custom header, or a session-specific URL.
- Open your MCP client’s server configuration. The location and exact UI differ by client; use its documented mechanism for adding an MCP server.
- Add the Playwright MCP server. Use the following configuration shape, replacing the endpoint with the exact URL from your provider:
{ "mcpServers": { "playwright": { "command": "npx", "args": [ "@playwright/mcp@latest", "--cdp-endpoint=https://YOUR_PROVIDER_CDP_ENDPOINT" ] } } } - Add authentication only as required. If the provider requires header-based authentication, use Playwright MCP’s documented
--cdp-headeroption or the provider’s secure environment-variable approach. Do not assume every provider uses the same header name or token format. - Restart or reload the MCP client if its configuration requires it, then confirm that the Playwright server starts and connects.
- Try a low-risk page first. Ask the client to navigate to a page you are allowed to access and inspect its accessibility snapshot. Then try a simple action such as clicking a link by its accessible name.
The key distinction is between the MCP server and the browser: Playwright MCP provides the tools the AI client uses, while the cloud provider hosts the browser session. A successful local server launch does not prove that the remote endpoint is reachable or authenticated.
Choose the right endpoint and launch options
Chromium CDP endpoint
For a cloud Chromium browser that exposes Chrome DevTools Protocol, pass its CDP URL with --cdp-endpoint. The endpoint must be reachable from the machine running Playwright MCP, and any provider-required authentication must be supplied in the provider’s documented way.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →#1 Best Overall
Remote Playwright endpoint
Some services expose a Playwright-compatible remote endpoint rather than a CDP endpoint. In that case, use --endpoint=wss://... with the exact URL supplied by the provider. Do not put a Playwright endpoint into --cdp-endpoint, or vice versa.
Headless execution and repeatable layout
For CI or a remote worker, add --headless. To reduce layout variation, specify a viewport such as --viewport-size=1280x720, or the dimensions your test expects. Choose --browser=chrome or another supported browser only when it matches the engine available from the endpoint. Device and mobile emulation can also be configured, but the provider’s browser capabilities and the page’s responsive behavior still affect the result.
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": [
"@playwright/mcp@latest",
"--cdp-endpoint=https://YOUR_PROVIDER_CDP_ENDPOINT",
"--headless",
"--viewport-size=1280x720",
"--browser=chrome"
]
}
}
}Use only options supported by the MCP server version you run and by the remote browser. Other configurable areas include proxy settings, CDP headers, and timeouts. Provider-specific constraints—such as browser engine, region, session duration, or concurrency—must be checked with that provider; they are not determined by Playwright MCP.
Run Playwright MCP as a separate HTTP server
Most users can let their MCP client launch the server as a local process. If you need the MCP server to run separately, start it with a port and point the client at its MCP route:
npx @playwright/mcp@latest --port 8931Configure the client’s server URL as http://localhost:8931/mcp. For a container or remote host, bind deliberately with --host and configure allowed hosts rather than exposing the service indiscriminately. Make sure the client can reach that host and port through any firewall, container network, or reverse proxy.
HTTP sessions use a five-second heartbeat timeout by default. A proxy or client that does not answer the heartbeat may disconnect even when the browser itself is still running. If that is the failure, check proxy and client ping handling and, where appropriate, adjust the documented PLAYWRIGHT_MCP_PING_TIMEOUT_MS setting.
Use snapshots and accessible names for browser actions
Playwright MCP is designed to let an AI client interact with pages through structured accessibility snapshots. In practice, the client can inspect the page’s accessible controls, then request actions such as clicking or filling a field by its accessible name. This is generally more robust than asking it to guess screen coordinates, especially when the viewport or page layout changes.
- Navigate to a permitted test page.
- Ask the client to inspect the accessibility snapshot and identify the intended control.
- Use the control’s accessible name to click or fill it.
- Inspect the resulting page state before continuing to another consequential action.
Cloud pages can differ from local pages because of region, network access, browser version, authentication, or bot checks. If a page behaves differently, check those variables before concluding that the MCP action itself is at fault.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchManage login state and parallel jobs safely
Persistent profiles
A persistent browser profile can retain cookies and local storage between sessions, which is useful when a task needs an existing login. Persistent state also carries risk: a later task using that profile may inherit its authentication and site data. Restrict access to profile storage and use an account appropriate to the task.
Profile locking and concurrency
A profile can be used by only one browser at a time. If another process holds it, startup can fail because the profile is locked. For parallel jobs, give each job a separate profile or use --isolated when the job should not share persistent browser state. Do not point simultaneous jobs at one profile directory and expect independent sessions.
Secrets and provider controls
The Playwright options documentation describes a secrets file that can redact matching values and substitute placeholders. That convenience is not a security boundary: protect the provider token with the provider’s own access controls, network restrictions, and secret-management practices. Avoid printing CDP URLs or credentials in CI logs, and revoke or rotate exposed tokens using the provider’s controls.
When cloud CDP is not the right mode
A cloud CDP session normally provides a remote browser, not your local browser’s full environment. It may not have a locally installed extension, your local profile, or access to an organization’s local single sign-on flow. If the task depends on those, use a provider-supported extension or remote-browser setup and verify that it actually supports the needed capability. Playwright MCP also has an extension mode for using an existing local tab; that is a different setup from connecting a cloud browser over CDP.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Repair Windows errors before they cause bigger problems3Fix the driver behind crashes, sound loss and screen glitchesTroubleshoot common connection and session failures
| Symptom | Likely cause | What to check or change |
|---|---|---|
| Connection refused or times out | The endpoint is unreachable from the MCP process, the session has ended, or required authentication is missing. | Confirm the session is active, copy the provider’s current CDP URL, test network reachability from the MCP host, and check required headers or tokens. Increase --cdp-timeout only after checking reachability and authentication. |
| MCP starts but cannot attach to the browser | The endpoint type or URL is wrong, or the provider requires a different connection method. | Check whether the provider supplied CDP or a Playwright endpoint. Use --cdp-endpoint for CDP or --endpoint for a remote Playwright endpoint. |
| Page renders differently than expected | The cloud engine, viewport, device settings, region, or session differs from the expected environment. | Confirm the provider’s browser engine; align --browser, viewport, device, and mobile settings with the test. Check whether the provider offers the required browser configuration. |
| Login disappears between runs | The session is not persistent, the wrong profile is being used, or the provider does not retain session state. | Use a persistent profile or provider-side session persistence when appropriate, and verify that the same session/profile is selected across runs. |
| Browser refuses to start with a profile | Another browser process is using that profile. | Stop the competing process, assign separate profiles to parallel jobs, or use --isolated if persistence is unnecessary. |
| HTTP MCP client disconnects unexpectedly | A proxy or client is not answering the five-second heartbeat. | Check proxy handling and client heartbeat behavior; adjust PLAYWRIGHT_MCP_PING_TIMEOUT_MS when needed and supported by the deployment. |
| Cloud page cannot complete SSO or use an extension | The cloud browser does not share the local browser’s extension or identity environment. | Use a provider-supported remote or extension workflow and confirm the required SSO and extension capabilities before relying on it. |
Performance, reliability, and cost considerations
With a remote browser, each operation depends on both the MCP process and the cloud session: endpoint latency, provider capacity, page load behavior, and session lifetime can all affect completion. Keep CI jobs explicit about viewport and browser, avoid unnecessary parallel sharing of state, and give navigation or action timeouts enough room for the target site and provider conditions. A longer timeout cannot repair an invalid endpoint, missing credentials, or an expired session.
Playwright MCP itself does not establish a cloud-browser provider’s price, quota, concurrency cap, data region, or retention policy. Check those details in the provider’s current terms and dashboard before estimating a workload. For stable automation, also confirm how the provider handles session startup, retries, browser versions, and termination; these vary by service.
Or skip the browser setup
If your task is to capture a page as an image or PDF rather than interact with a live browser, ScreenshotNeo is a simpler alternative. It is a screenshot API and MCP server; it is not a substitute for Playwright MCP when you need to click through a workflow, fill forms, or use a persistent interactive session. One GET request returns a PNG, JPEG, WebP, or PDF. See the ScreenshotNeo service and API documentation.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpFor Python:
import requests
r = requests.get(
"https://api.screenshotneo.com/v1/shot",
params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
timeout=90,
)
open("shot.webp", "wb").write(r.content)For Node.js:
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);ScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before capture; each cleanup step can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers identify the page verdict and billing status. Its MCP server includes tools for taking screenshots, getting page information, and capturing PDFs. The Free plan includes 1,000 screenshots per month without a card; paid plans start at $5 for 3,000 screenshots, with every feature on every plan. Sign up free for 1,000 screenshots a month, with no card required.
Recommended Free Tools
Frequently Asked Questions
Can Playwright MCP connect to any cloud browser?
Only if the service exposes a compatible CDP or remote Playwright endpoint that the MCP process can reach and authenticate to. Confirm those capabilities with the specific provider.
Does a CDP URL contain a secret?
Treat it as sensitive: provider endpoints may include session credentials or grant access to a running browser. Store it like a token and avoid sharing it in prompts or logs.
Can I use the same cloud-browser profile for concurrent CI jobs?
No. A persistent profile is intended for one browser at a time; assign separate profiles or use isolated sessions for parallel work.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
