Connect Codex to Playwright

What you get

Playwright MCP runs a real browser and hands Codex the tools to drive it. Microsoft’s README says the server uses “Playwright’s accessibility tree, not pixel-based input”, so Codex reads back element roles and labels as structured data and can find the login button without a vision model. You pick the engine with --browser, and the README lists chrome, firefox, webkit, and msedge.

The core automation tools are on by default: browser_navigate, browser_navigate_back, browser_click, browser_type, browser_fill_form, browser_hover, browser_drag, browser_drop, browser_select_option, browser_press_key, browser_wait_for, browser_snapshot, browser_take_screenshot, browser_find, browser_evaluate, browser_file_upload, browser_console_messages, browser_handle_dialog, browser_network_request, browser_network_requests, browser_run_code_unsafe, browser_resize, and browser_close. browser_tabs sits in its own tab-management group and is also on by default.

Everything else is opt-in. The README’s tool reference labels seven groups as --caps=<name>: vision (coordinate mouse tools like browser_mouse_click_xy), pdf (browser_pdf_save), devtools (tracing, video, element highlighting), network (browser_route and friends), storage (cookies, localStorage, sessionStorage), testing (assertions like browser_verify_text_visible), and config (browser_get_config). One caveat: the options table in that same README lists only vision, pdf, and devtools as accepted --caps values, while the tool reference documents all seven. Run npx @playwright/mcp@latest --help to see which ones your build takes. If a tool you expected never shows up in Codex, check whether it needs a --caps flag before you assume the server is broken.

There is no auth to configure. The server runs locally and talks to Codex over stdio.

Setup

The latest published version is 0.0.78 (npm, 2026-07-09). Microsoft’s README has a Codex section, and it gives this one-liner:

codex mcp add playwright npx "@playwright/mcp@latest"

Or write the block yourself in ~/.codex/config.toml. For the general shape of an [mcp_servers.<id>] entry, see Connect an MCP server. The README’s block is:

[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]
startup_timeout_sec = 60

startup_timeout_sec = 60 is the one line not in Microsoft’s example. Gotchas below covers why.

Headless and profile flags. Per the README, the browser runs headed unless you pass --headless, and --isolated keeps the profile in memory instead of writing it to disk. Both go in args:

args = ["@playwright/mcp@latest", "--headless", "--isolated"]

Confirm it initialized. Run codex mcp list and check that playwright shows up. If it doesn’t, read the Windows gotcha below before you file a bug.

Only if you need one browser shared across clients. The README documents a standalone mode: run npx @playwright/mcp@latest --port 8931 yourself as a long-running process, then point the Codex entry at url = "http://localhost:8931/mcp" instead of command and args. The README shows that client config in JSON, and Codex takes the same value as TOML. We have not run this against Codex end to end, so treat it as documented rather than verified.

If your automation types a password or API key into a page, that value goes in an environment variable or the dotenv file --secrets reads. Never inline it in config.toml. See Secrets in env vars.

Gotchas

Four issues in the openai/codex tracker cover Playwright, 103 comments between them, and none of them are about writing the config block wrong.

Windows: “program not found.” #2945 (closed, 46 comments) was filed 2025-08-30 by a Windows 11 user on codex-cli 0.25.0 who followed the install instructions and got MCP client for playwright failed to start: program not found. PR #3828 spells out the cause: npx on Windows is a batch script (npx.cmd) rather than an executable, and Rust’s std::process::Command bypasses the shell, so it cannot run one. That PR merged 2025-11-16 and closed #2945 the same day, resolving programs through PATH/PATHEXT with the which crate. Current builds should not hit this. On an older build, wrap the command (cmd /c npx @playwright/mcp@latest) or point command at the absolute path, for example C:\Program Files\nodejs\npx.cmd.

Approval prompts on every action. #13476 (open, 30 comments, 39 reactions) reports that on codex-cli 0.107.0, approval_policy = "never" does not stop per-action prompts for browser_click, browser_type, and the rest, which turns a multi-step Playwright run into a click-through exercise. The reporter wants a way to trust one local MCP server without dropping safety globally. #15169 (closed, 14 comments) is the same pain from the other direction: after a macOS Codex App update on 2026-03-19 (build 26.317.21539), the session-scoped “approve for this session” option that used to cover repeated Playwright calls went away. Both land on one key documented on the MCP mechanism page: set default_tools_approval_mode = "writes" on the [mcp_servers.playwright] block so read-only tools like browser_snapshot run without a prompt and only state-changing actions ask.

Processes leak after long sessions. #17832 (open, 13 comments) reports 213 orphaned npm exec @playwright/mcp@latest and node process pairs under a codex app-server tree on codex-cli 0.120.0, holding 13.6 GB of RSS. The reporter frames it as a regression: #16895 was closed 2026-04-09 as a fix for stdio child-process cleanup, and they hit it again on 2026-04-14 running subagent workflows. Their workaround is blunt: pkill -f playwright-mcp. Watch your process list if you run Codex subagents against this server for long stretches.

Cold npx needs more than 10 seconds. The first launch downloads the @playwright/mcp package and, separately, the Playwright browser binaries, both before the server can answer Codex’s handshake. The default startup_timeout_sec of 10 does not cover that. See startup_timeout_sec for the key and the handshake error page for what the failure looks like.

One persistent profile, one browser. Microsoft’s README warns that a persistent profile works with only one browser instance at a time, so concurrent MCP clients sharing the same workspace will conflict. To run more than one Codex session against Playwright at once, start each extra client with --isolated or point it at a distinct --user-data-dir.

Related

• Connect an MCP server: the general [mcp_servers.<id>] shape, JSON-to-TOML translation, and approval-mode keys
• startup_timeout_sec: why cold npx needs more than the 10-second default
• Secrets in env vars: keeping credentials out of a committed config.toml
• “handshaking with MCP server failed”: when the connection dies at startup
• Install Codex CLI: if codex mcp add isn’t a recognized command yet