Playwright MCP for Codex: configure, connect and verify a browser task
Codex says it added a browser server. The next reply describes the page, but there is no browser call to inspect. Before changing a selector, check whether this conversation actually loaded Playwright MCP.
Playwright MCP for Codex gives the coding agent browser tools through Microsoft's @playwright/mcp server. Codex chooses a tool and arguments; the server performs the browser operation. A registered launcher, an initialized connection and a verified task result are separate checkpoints.
The configuration follows official documentation checked October 15, 2026. Supplied screenshots from that day record a native Codex Playwright MCP task and a separate ego(lite) run. Their recorded results are described below; the local evidence tables are summaries, separate from the live source pages.
How do you add Playwright MCP to Codex?
Codex can register Playwright MCP as a local stdio server. Use a supported Node.js LTS with npm available to the process that starts the server. Microsoft's repository documents the package; the Codex MCP guide defines the client configuration.
Inspect existing server names before adding another entry. The following variant uses a fresh isolated browser session for the public verification task:
codex mcp add playwright -- npx -y @playwright/mcp@latest --isolated
codex mcp list
codex mcp get playwrightThe add command changes configuration. List and get inspect registration; neither command proves that the current conversation can invoke a browser tool. Review their output privately because other server entries can contain credentials.
Resolve and record the installed package version once the connection works. @latest is convenient during setup, but it doesn't identify a reproducible release. The server package, browser build and Codex client are separate versions.
Which Codex configuration does the session load?
Codex stores MCP entries in config.toml. Current documentation describes user configuration at ~/.codex/config.toml and project configuration at .codex/config.toml; loading also depends on the client, host and applicable trust or managed settings. Inspect the definition active in the session where the task will run.
A TOML entry equivalent to the isolated launcher is:
[mcp_servers.playwright]
command = "npx"
args = ["-y", "@playwright/mcp@latest", "--isolated"]
startup_timeout_sec = 30
tool_timeout_sec = 60These timeout values are example limits. Startup timeout bounds initialization; tool timeout bounds an initialized call. Increasing either value won't repair a wrong URL, an unavailable executable or a missing target.
The official Codex configuration reference is the authority for field names. Generic mcpServers JSON belongs to clients that consume that format; don't paste it directly into TOML.
After changing configuration, restart or refresh the relevant client using its documented control and inspect the active tools. A desktop process can have a different PATH from the terminal where npx worked. A remote executor also needs its own reachable runtime and browser environment.
How do you prove Codex used Playwright MCP?
A real invocation must identify the configured server and the tool it called. Ask Codex to navigate to a known public page and return the selected URL plus a fresh snapshot. Use the tool names and schemas exposed by the installed version.
Use the configured Playwright MCP server for browser operations.
Open https://demo.playwright.dev/todomvc/#/ in a headed browser.
Report the server and tool actually called, the current URL,
and a fresh snapshot identifying the todo input.
If this session has no Playwright MCP tools, report that fact.
Do not replace the task with a standalone browser script.Playwright's MCP introduction describes accessibility snapshots and browser tools. Snapshot references belong to observed page state. Obtain new references after navigation or a material rerender instead of reusing identifiers from a tutorial.
The evidence checkpoints answer different questions:
| Checkpoint | Evidence to retain | Remaining question |
|---|---|---|
| Registered | Effective launcher or endpoint | Did it initialize? |
| Connected | Available tools in this client session | Can it reach the browser? |
| Browser reached | Actual navigation and current-page response | Did the requested change occur? |
| Task accepted | Fresh state after the final action | Is the result complete and correct? |
A shell-launched MCP logging client can help diagnose the server, but it is a different connection path from native Codex tool invocation. Label that path explicitly. Running a standalone Playwright script proves a script worked, even if Codex wrote it.
In the supplied October 15 run, Codex invoked native tools from the existing dedicated codex_playwright_todomvc server over stdio. Configuration remained unchanged. The first browser call failed because its required browser was missing. The record preserves that error, installation using the official package command, and one explicit setup recheck. The corrected saved inventory contains 25 tools; this is a count for that session, not a guaranteed tool count for other installations.
Which browser state should you use?
An isolated profile is a useful starting point for a public setup check. It separates the example from personal browsing state. The Playwright MCP profile documentation distinguishes persistent profiles, isolated sessions and extension-based connections.
| Mode | Useful purpose | Verification boundary |
|---|---|---|
| Isolated | Clean public task and repeatable starting state | Reload preserves the active session; browser closure can discard in-memory storage |
| Dedicated persistent profile | Resume a deliberately retained test context | Inspect existing state before retrying a write |
| Extension connection | Work with explicitly selected existing browser context | Review the actual session access and connection consent |
The server runs headed by default; --headless changes that behavior. Leave headed mode enabled when a person needs screenshots. Existing login state is not inherited simply because Chrome is already open elsewhere.
Keep each concurrent browser instance on a separate profile. A profile ownership error is a reason to select a dedicated test profile, not to close unrelated user windows.
What should the first real task verify?
The TodoMVC demo supports a small persistence contract with no personal account. Generate one unique item, verify its initial state, complete the same item and reload. Acceptance requires both the exact text and completed state to remain.
Use a task-specific value such as Codex Playwright check <run-id>. Record the initial list before creating it. Preserve unrelated items, and inspect the exact matching row rather than using the first checkbox on the page.
Save the actual MCP responses and JSON checks. The minimum useful result includes the created-row count, initial checkbox state, final checkbox state, completed styling, source URL and evidence after reload. A locally generated table should be labelled as a summary, with the real browser tab retained separately.
A deliberate missing-target check can test the stopping boundary without modifying the website: look for <exact-created-text>-missing, confirm zero matches, and issue no click to that target. Record the guard result separately from the successful task. This check demonstrates target validation; it is not a connection outage or an application defect.
The supplied native MCP result is PASS for one functional example. Run 20261015T062123Z-359f0f1e created exactly one initially unchecked item, found zero exact matches for the deliberately absent -missing target and issued no action to it. After completing the original item and reloading, the record reports preserved full text, checked checkbox, completed class and grey line-through styling. The isolated session began with no unrelated todos.
The recorded environment was Playwright MCP 0.0.83, Playwright 1.64.0-alpha-1790635538000 and Chrome for Testing 155.0.8059.12. The controller record lists desktop 26.1007.30912 and bundled Codex 0.162.0-alpha.17.2. These are tested versions, not installation requirements. The missing-browser failure, favicon 404 and corrected inspection or packaging errors are retained; the result reports zero application retries and zero human interventions.
Recorded workflow time was 26.319 seconds from immediately before navigation through the post-reload verification response. It includes intervening reasoning and evidence handling, excludes setup and report packaging, and does not isolate server execution time. One successful public-demo task does not establish reliability or a speed advantage.
How do you diagnose a failed connection or action?
The first failed checkpoint determines the next inspection. Preserve the original error before editing a configuration or replacing a selector.
| Symptom | First inspection | Bounded response |
|---|---|---|
| Server absent | Effective config, enabled state and refreshed client | Correct the intended entry and reload that client |
| Startup fails | Executable path, package resolution and stderr | Repair the launcher before changing page instructions |
| Browser will not launch | Installed browser, display access and profile ownership | Use the documented browser installation route or a separate profile |
| Tool rejects arguments | Current installed schema | Correct arguments against that schema |
| Element ref fails | Current tab, URL and fresh snapshot | Re-identify the exact target |
| Call times out after a write | Actual application state | Check whether the write happened before replaying it |
A longer timeout cannot make a missing element exist. A second create action can also duplicate work if the first action succeeded but its response was lost. Read the page before retrying.
Keep fixes as later attempts with their own records. For broader route selection, see the Codex browser guide; for DevTools-specific inspection, see Chrome DevTools MCP vs Playwright MCP.
Where does ego(lite) help with browser review?
A visible ego(lite) Space is a separate execution workspace when the source page needs human inspection or takeover during an agent task. Its ego-browser connection and Space controls give the reader a concrete alternative for keeping the browser task visible.
The supplied independent reference run used Codex through the installed ego-browser nodejs helper in a Space named Codex Playwright comparison: ego. Its task instructed the controller to avoid Playwright MCP, standalone Playwright, direct HTTP and other runs' outputs for browser operations. The original controller-plus-Space captures identify that separate execution path.
Use Playwright MCP when the workflow needs its tool interface. Choose an ego(lite) Space when visible collaboration is the reason for the browser session. An independent Space run cannot certify that a Codex MCP configuration is correct, and it does not produce a Playwright Test CI report.
Independent run 20261015T062827Z-df6d2515 reports PASS: exactly one new item, initially unchecked; zero matches and zero actions for the absent target; and full text, checked state, completed class, line-through and completed color preserved after reload. All five existing rows retained their text, state and order. The recorded ego/helper version was 0.6.0.5, CLI-reported Chromium 154.0.8037.44 and skill guide 2.1.0.
The independent record reports zero action retries and zero human task interventions. Setup required resolving a stale nested skill path; an optional Browser.getVersion query was unsupported and an optional macOS inventory query failed. Those inspection issues are separate from the passing todo checks.
Its 47.679-second workflow measurement runs from the first browser round through saved verification and includes orchestration and evidence collection. Initialization through Space release was separately recorded as 126.264 seconds, excluding earlier skill lookup and final packaging. These boundaries and initial browser states differ from the native MCP run. Neither number supports a head-to-head speed ranking; isolated browser-engine time remains unknown.
FAQ
The following questions address configuration and evidence boundaries that affect a first Codex browser task.
Is Playwright MCP the same as Playwright Test?
Playwright MCP exposes browser operations to an MCP client. Playwright Test runs authored tests with fixtures, assertions and reports. An interactive MCP task does not automatically create a regression suite.
Does Codex require JSON for Playwright MCP?
Codex's direct server configuration uses TOML. Other clients may use mcpServers JSON, so follow the configuration format for the actual client.
Does a server listed by the CLI prove it works in the app?
A listed server proves registration in the inspected configuration. Confirm tool availability and a real browser call in the app conversation as well.
Do I need my personal Chrome profile?
A public verification task does not require a personal profile. Use an isolated or dedicated test profile and attach an existing session only deliberately.
Will an isolated session survive a reload?
Reload keeps the current browser session, so it can test page persistence within that session. Closing the isolated browser can discard its in-memory state.
Why does npx work in Terminal but fail from Codex?
The client process may have a different PATH or execution environment. Inspect the actual launcher error and runtime location before changing browser selectors.
Can I use a shell wrapper when native tools are missing?
A wrapper can diagnose MCP communication if its role is disclosed. It does not prove native tool availability in the original Codex session.
Should I reuse an element ref after reconnecting?
A reconnected session needs a fresh page observation. Confirm the current tab and target before supplying a new reference.
Can I declare success from the final screenshot?
A screenshot helps a person inspect the visible result. Pair it with exact row and state checks after reload so a similar-looking item cannot pass unnoticed.
Can one successful example establish reliability?
One example establishes an observed outcome for that task and environment. A reliability claim needs repeated runs with retained failures and a declared acceptance method.
Related reading
The Playwright MCP setup overview covers other clients, while browser agent verification explains completion checks. When visible source review is the next step, download ego(lite) and use a dedicated Space for the task.
