Playwright MCP Persistent, Isolated, and Browser Extension Profiles

Use a Playwright MCP isolated profile when every QA session should begin from controlled state and discard changes when the browser closes. Use the default persistent profile when repeated local work should retain login state, cookies, and localStorage. Use browser-extension mode only when the agent intentionally needs an existing Chrome or Edge tab, authenticated session, or installed extension. The choice determines reproducibility, parallelism, and exposure: isolation favors repeatable tests, persistence favors continuity, and extension attachment favors convenience while sharing the richest personal browser state.

The broader architecture is in the Playwright MCP browser automation guide. Before selecting state, review the server configuration reference, assertion and generation workflow, and security best practices. Teams can add domain-specific guidance from /skills, compare with the author-qualified Playwright CLI skill, and connect these choices to the existing Playwright test agents in Claude Code guide.

Make State a Test-Design Decision

Profile selection is not a cosmetic startup preference. It decides where the browser gets authentication, what survives a restart, whether previous work can influence the current result, and how easily two agents can run at once. A scenario that passes only because a developer logged in yesterday is different from one that starts from a reviewed storage-state fixture. A checkout flow run in a browser containing personal addresses and payment state has a different risk from the same flow in a fresh test account.

The official Profile & State documentation presents three modes:

• Persistent is the MCP default and keeps login state, cookies, and localStorage between sessions.
• Isolated starts each session without saved profile state and loses session storage when the browser closes.
• Browser extension connects to tabs in an existing browser rather than launching a separate profile.

Ask four questions before choosing:

1. Must the initial state be reproducible by another engineer or CI worker?
2. Is interactive SSO or 2FA impossible or undesirable to repeat in a separate automation profile?
3. Can the session touch personal, production, or otherwise sensitive browser state?
4. Will multiple MCP clients run concurrently against the same workspace?

The answers usually make the mode clear. Reproducible regression generation points to isolated state. Long local investigations with a dedicated test identity may use persistence. A one-off task that depends on an already authenticated enterprise tab may require extension mode, but only with explicit scope and human awareness.

Compare the Three Profile Models

Mode	State source	State after browser close	Parallel behavior	Best fit	Main risk
Persistent, default	Playwright MCP-managed profile or custom --user-data-dir	Cookies, login state, and localStorage remain on disk	One browser instance can use a persistent profile at a time	Repeated local exploration with a dedicated account	Hidden carry-over can mask setup or contaminate results
Isolated	Fresh in-memory context, optionally seeded by --storage-state	Session changes are discarded	Separate sessions avoid a shared persistent-profile lock	Reproducible QA, generation, and parallel agents	Required setup must be supplied explicitly
Browser extension	Selected tab in an existing Chrome or Edge profile	State remains part of that existing browser	Behavior depends on selected tabs and active browser state	SSO, 2FA, existing tabs, installed extensions	Agent can act inside a high-value personal or work session

No row is universally superior. "Persistent" does not mean more reliable, and "isolated" does not mean unauthenticated. An isolated context can start authenticated from storage state. Extension mode does not copy a session into a clean profile; it attaches to the browser state already in use.

Persistent Mode: Continuity by Default

Playwright MCP preserves profile state by default. The official docs say each project receives a separate profile automatically based on the workspace. The Microsoft repository further documents managed cache locations by platform and allows an override with --user-data-dir. In practice, the important contract is not the exact cache path but that authentication and local browser data can survive closing and reopening the MCP server for the same project context.

The minimum persistent configuration is simply the normal entry:

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

Choose a custom directory only when ownership and lifecycle are explicit:

{
  "mcpServers": {
    "playwright-qa": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--user-data-dir=./.playwright-mcp/qa-profile"
      ]
    }
  }
}

This directory is browser state, not ordinary test output. It can contain authenticated cookies and origin data. Do not commit it, attach it to a bug without review, or share it as a convenient login fixture. Give it a dedicated test identity and a documented cleanup or rotation procedure.

Persistent mode is useful for a multi-day exploratory investigation. An engineer can authenticate once, reproduce a problem, close the client, and continue later without repeating login. It also helps when repeated setup is expensive but the state is safe and intentionally retained.

The same continuity can invalidate a test conclusion. A feature flag in localStorage, a dismissed onboarding dialog, a cart item, or an expired-but-present cookie can make the page differ from a new user's page. Before reporting a defect or generating a regression test, record the profile mode and determine whether retained state is part of the scenario.

Avoid Persistent-Profile Concurrency Conflicts

The official Microsoft repository warns that a persistent profile can be used by only one browser instance at a time. Two MCP clients sharing the same workspace-derived profile can conflict. This is a browser-profile ownership constraint, not a reason to kill random processes or delete state while another session is active.

For concurrent agents, choose one of these patterns:

• Start each agent with --isolated when no disk persistence is needed.
• Assign a distinct --user-data-dir to each persistent client.
• Serialize access to one persistent browser when sharing its exact state is intentional.
• Use separate test identities and data even when browser directories are separate.

Distinct profile directories solve the file ownership collision, but they do not isolate server-side accounts. If two agents sign into the same test user, they can still change the same cart, draft, preferences, or session records. Browser isolation and test-data isolation are separate controls.

Do not use extension mode as a workaround for profile locking. That changes the test to an existing browser and can expose broader state. Resolve concurrency at the profile and account level instead.

Isolated Mode: A Clean, In-Memory Session

Add --isolated when browser profile changes should not be saved to disk. The documented mode starts each session fresh; when MCP closes the browser, its session storage is lost. This makes the starting state visible and the ending state disposable, which is usually the strongest default for repeatable QA exploration and test generation.

{
  "mcpServers": {
    "playwright-isolated": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--isolated",
        "--caps=testing"
      ]
    }
  }
}

Isolation exposes missing prerequisites quickly. If the app requires a seeded organization, feature flag, consent cookie, or login fixture, the first snapshot will reveal that setup rather than inheriting it silently. The agent can then follow an approved setup flow or load reviewed state.

"In memory" does not mean "no side effects." The browser can still submit forms, create records, trigger messages, or mutate remote systems. Closing the browser discards local profile state; it does not roll back application data. Use test accounts, disposable records, mocked services, or cleanup procedures where the scenario has external effects.

Isolation also does not create a security sandbox. The Playwright repository labels its file restrictions and origin controls as convenience guardrails, and Playwright MCP itself is not a security boundary. An isolated profile limits state carry-over; client permissions, process containment, network policy, and target authorization still matter.

Seed an Isolated Session with Storage State

An isolated profile can begin authenticated. Pass a storage-state file at startup:

{
  "mcpServers": {
    "playwright-authenticated-test": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--isolated",
        "--storage-state=./test-state/qa-user.json",
        "--caps=testing"
      ]
    }
  }
}

The storage documentation defines storage state as cookies plus localStorage saved to a JSON file. It is the primary documented mechanism for carrying authentication into another session. It does not preserve every possible browser artifact, and sessionStorage is session-scoped rather than part of the persisted storage-state description.

A safe workflow has a clear producer and consumer:

1. Authenticate with a dedicated QA account through an approved setup.
2. Save state to a controlled file.
3. Store it outside source control unless the contents are demonstrably non-sensitive.
4. Start isolated consumers with --storage-state.
5. Rotate or regenerate state when credentials, roles, or sessions change.
6. Revoke the underlying session if the file is exposed.

The storage capability also exposes browser_storage_state and browser_set_storage_state for save and restore during a connected workflow:

browser_storage_state
  State saved to: auth-state.json

browser_set_storage_state { path: "./auth-state.json" }
browser_navigate { url: "https://app.example.com/dashboard" }
browser_snapshot

Enable --caps=storage when the agent needs those tools. Startup with --storage-state is a server configuration choice; it does not require the agent to manipulate individual cookies or storage keys during every task.

Treat the file as a credential-bearing artifact even if it contains no password. Session cookies can authorize access. Never paste its contents into a model prompt, console transcript, article, or ticket. Scope the account and session so compromise has limited impact.

Browser Extension Mode: Attach to Existing State

Extension mode connects Playwright MCP to an existing browser rather than launching a new browser profile. The current connecting-to-browsers guide documents Chrome and Edge use cases: reusing SSO or 2FA authentication, interacting with pages that depend on installed extensions, and automating tabs already open.

The server configuration is short:

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

Install the official Playwright Extension in the target Chrome or Edge browser first. On first interaction, the extension presents a tab-selection page so the user can choose which tab the model will control. That selection is an important consent boundary: close unrelated tabs, choose the narrowest target, and remain aware that navigation from the selected tab can reach other origins allowed by the active session.

The official extension README says connection approval is required by default. It also documents a unique PLAYWRIGHT_MCP_EXTENSION_TOKEN displayed by the extension, which can bypass repeated approval when placed in the server environment:

{
  "mcpServers": {
    "playwright-extension": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--extension"],
      "env": {
        "PLAYWRIGHT_MCP_EXTENSION_TOKEN": "replace-with-token-from-extension-ui"
      }
    }
  }
}

Do not commit the real token. Bypassing a repeated approval prompt trades friction for standing authorization between the server and browser profile. Use the manual approval flow when repeated unattended attachment is not required, and protect or rotate the token according to the value of the browser profile it can reach.

Extension mode should be exceptional for destructive QA. An agent attached to a normal work profile may have access to email, admin consoles, production dashboards, cloud tools, and stored sessions. A prompt that says "test checkout" is not enough scope if the tab can navigate into a real account. Prefer a separate browser profile containing only dedicated test identities.

Do Not Confuse Extension, CDP, and Persistent Profiles

Playwright MCP also supports connecting to a running Chromium-family browser through --cdp-endpoint, including documented Chrome or Edge channels and explicit CDP URLs. That is a connection mechanism, not one of the three state-policy recommendations in this guide. It attaches to whatever state the target browser exposes through that connection.

A custom --user-data-dir still launches a Playwright-managed persistent browser with the specified profile directory. --extension uses the installed extension and selected existing tabs. --cdp-endpoint connects through Chrome DevTools Protocol. These choices are not interchangeable flags for "keep me logged in."

State ownership determines the right option:

• Use a custom user-data directory when Playwright MCP should own a dedicated persistent automation profile.
• Use extension mode when the required state belongs to an existing interactive browser and tab selection is part of the workflow.
• Use CDP when an existing Chromium endpoint is already managed and explicitly exposed for automation.
• Use isolated state when reproducibility matters more than retaining browser-local changes.

The JSON schema notes that browser configuration is ignored when extension mode is selected. That is coherent: Playwright MCP is not launching the attached browser with a new viewport, executable, or profile. Test the state that actually exists rather than assuming launch options reconfigured it.

Match Profiles to Common QA Jobs

Regression scenario generation

Use isolated mode, a dedicated account, and reviewed storage state if authentication is required. The goal is a flow another worker can reproduce without inheriting the explorer's profile.

Multi-day exploratory investigation

Use a dedicated persistent profile when retaining state is part of the investigation. Record the profile choice in evidence, and reset it before testing first-run behavior.

Enterprise SSO behind interactive controls

Use extension mode only if a separate automated login or storage-state fixture is unavailable or prohibited. Select one test tab, use a dedicated browser profile, and keep human approval unless unattended attachment is an explicit requirement.

Parallel agent exploration

Use isolated mode for each client or distinct persistent profile directories. Give agents separate application data where their actions can collide server-side.

Onboarding and new-user validation

Use isolated mode without saved state. A persistent profile may already contain consent, feature, or onboarding markers and produce a false pass.

Installed-extension compatibility testing

Use browser-extension mode when the page genuinely depends on extensions installed in that existing browser. Document which extensions and versions are part of the scenario because they are external state.

Reset and Rotate State Intentionally

Closing an isolated browser resets its local session by design. Resetting a persistent session requires retiring or clearing its profile state, and the official repository says the managed profile can be deleted between sessions to clear offline state. Do that only when no browser owns the profile and when losing the retained login is intended.

For a custom --user-data-dir, make cleanup a named team operation rather than an ad hoc deletion during a run. For storage-state files, rotate on expiry, role changes, credential changes, suspected exposure, or environment reset. For extension mode, sign out or close the dedicated browser profile when the authorized task is over, and remove any unattended extension token that is no longer needed.

Reset browser state and reset server-side test data separately. Clearing cookies does not delete a created order. Deleting a profile does not revoke every server session unless the application does so. A complete cleanup plan identifies browser state, application records, external messages, and credentials.

Profile Mode Limits and Version Notes

This guide reflects official Playwright MCP documentation available on July 14, 2026. It describes MCP behavior, not Playwright CLI session behavior; the CLI has different defaults and session controls. Examples use @playwright/mcp@latest, while teams that need reproducibility should pin and validate a reviewed version.

Persistent profile paths and workspace-derived naming are implementation details that can evolve. Use --user-data-dir when a stable, team-owned directory is required rather than scripting against an assumed managed cache name. A persistent profile remains single-owner even if multiple clients know its path.

Storage state covers cookies and localStorage in the official MCP storage workflow, not every property of a full interactive browser. It can expire or become invalid when the server revokes a session. Extension mode is limited to supported Chromium-family browsers and depends on the official extension. None of the modes undoes remote side effects, prevents prompt-driven destructive actions, or substitutes for process and network security.

FAQ: Profile Selection

Is Playwright MCP persistent or isolated by default?

Playwright MCP uses a persistent profile by default, preserving login state, cookies, and localStorage between sessions. Add --isolated when the profile should remain in memory and be discarded on browser close.

When should I use a Playwright MCP isolated profile?

Use it for reproducible QA, clean first-run checks, parallel agent sessions, and test generation that should not depend on previous browsing. Seed approved authentication with --storage-state when a fresh but logged-in start is required.

Can an isolated profile still be authenticated?

Yes. Pass --storage-state=./path/to/state.json to load cookies and localStorage at startup, or enable the storage capability and restore state through its documented tool. Protect that file as an authentication artifact.

Why do two persistent MCP sessions conflict?

A persistent browser profile can be owned by only one browser instance at a time. Run additional clients in isolated mode or give each a distinct --user-data-dir. Also separate their application accounts or data if server-side actions can collide.

Does browser extension mode copy my login into an isolated browser?

No. It attaches to selected tabs in the existing Chrome or Edge browser and reuses that browser's sessions, cookies, and extensions. The state remains part of the existing browser profile.

What is the difference between storage state and a user-data directory?

Storage state is a portable JSON representation of cookies and localStorage used to seed a context. A user-data directory is a persistent browser profile containing broader browser data and is owned by a launched browser instance.

Is the Playwright extension token safe to commit?

No. The token can bypass repeated connection approval for that browser profile. Keep the real value out of source control and shared examples, restrict access to it, and remove or rotate it when unattended connection is no longer required.

Does closing an isolated browser roll back test data?

No. It discards browser-local profile state. Orders, records, emails, uploads, and other remote side effects remain unless the application, test environment, or cleanup workflow removes them.

Should test generation use my everyday browser profile?

Avoid it. An everyday profile contains unrelated sessions and personalized state that can alter results and expand exposure. Prefer isolated mode with controlled state or a dedicated persistent or extension browser profile used only for QA.