How to connect Codex to the Playwright MCP server

Connecting Codex to a local browser automation backend makes repeatable web tasks possible, including capturing snapshots, extracting structured data, and validating UI flows without manual clicking.

The Playwright MCP server runs as a local process and exposes the Model Context Protocol (MCP) over HTTP on a chosen port. Once registered in /~/.codex/config.toml, Codex routes browser actions through the endpoint during a session in both the CLI and IDE extension.

The MCP server process must be started before the Codex MCP entry is used, and it must remain running for the duration of automation work. Keeping the endpoint bound to localhost reduces exposure, and the configured URL must be reachable from the environment where codex runs (local shell, container, or remote host).

1. Open a terminal window dedicated to the Playwright MCP server process.

   Keeping the server in its own terminal keeps logs visible during automation runs.

2. Start the Playwright MCP server on a local port.

   $ npx @playwright/mcp --headless --port 8931
   Playwright MCP server listening on http://127.0.0.1:8931

   Use a different port if 8931 is already in use.

3. Keep the MCP server process running while Codex is using browser tools.

   Stopping the server process breaks active automation calls and may cause tool failures mid-session.

4. Add the Playwright MCP server to Codex.

   $ codex mcp add playwright-mcp --url http://127.0.0.1:8931

   Use --bearer-token-env-var if the server expects a bearer token header.

5. Retrieve the saved entry to confirm the transport and URL.

   $ codex mcp get playwright-mcp --json
   {
     "name": "playwright-mcp",
     "enabled": true,
     "disabled_reason": null,
     "transport": {
       "type": "streamable_http",
       "url": "http://127.0.0.1:8931",
       "bearer_token_env_var": null,
       "http_headers": null,
       "env_http_headers": null
     },
     "enabled_tools": null,
     "disabled_tools": null,
     "startup_timeout_sec": null,
     "tool_timeout_sec": null
   }

6. List MCP servers to confirm the entry is available.

   $ codex mcp list
   Name            Url                    Bearer Token Env Var  Status   Auth
   playwright-mcp  http://127.0.0.1:8931  -                     enabled  Unsupported