Playwright MCP with a remote browser

Playwright MCP exposes browser operations as tools for an MCP client. When configured with a CDP endpoint, the MCP server can attach to an existing Chromium browser. The MCP server runs with your agent or tool host; the browser can run in separate infrastructure.

Connection model

MCP client → Playwright MCP server → CDP → Remote Chromium → Website

The official server documents the CDP endpoint setting as both a CLI option and an environment variable. See the Playwright MCP repository for the supported configuration of your installed version.

Configure the server environment

Obtain a browser endpoint from your session provider and inject it securely into the process environment. The following shell example assumes Node.js and npm are installed and that you have already set the secret endpoint variable:

# REMOTE_BROWSER_CDP_URL is supplied by your secret manager or local environment.
: "${REMOTE_BROWSER_CDP_URL:?Set your authenticated browser endpoint}"
export PLAYWRIGHT_MCP_CDP_ENDPOINT="$REMOTE_BROWSER_CDP_URL"
npx @playwright/mcp

For repeatable deployments, pin the package version in your project rather than depending on a moving package release. If your MCP client launches the server itself, configure the same environment variable in that server's environment using your client's supported secret mechanism.

This is a documented upstream attachment path, not a claim that this exact package version has been exercised against every Remote Browser feature.

Verify a read-only task first

1. Confirm the endpoint refers to the intended browser and account.
2. Start the MCP server and connect your MCP client.
3. Ask it to open a harmless public page and report the page title.
4. Confirm the navigation in your runtime's viewer, if available.
5. Check how stopping the MCP server affects the browser allocation.

The website requests originate in the remote browser environment. A download or file upload may therefore involve two different filesystems. Test artifact transfer explicitly before relying on paths returned by a tool.

Troubleshoot by layer

A server launch failure concerns package installation or the client launch configuration. An attachment failure concerns the endpoint, authentication, network, or runtime readiness. A successful attachment followed by a login redirect concerns website authentication and profile state.

Restrict access to the MCP process and avoid exposing an unauthenticated tool server. Treat a CDP endpoint as access to the browser's active account. Decide which component releases the hosted allocation when the task is done.

For direct library usage, use Playwright over CDP. For an alternative coding-agent setup, use the Remote Browser Agent skill. Review session lifetimes before adding reconnect behavior.