Playwright

Overview

The Playwright app drives a web browser through query commands, so an agent or an operator can read a site that offers no API and act on it. The browser does not run on the Sonar host. It runs on a separate Playwright MCP server, and this app speaks to that server over MCP (JSON-RPC over HTTP).

Sonar (playwright app)
   |  MCP over HTTP        <- the app speaks only this protocol
   v
Playwright MCP server (separate host or container)
   |__ Chromium + system libraries
      |  HTTPS
      v
   target web site

Installing the app therefore has two parts: standing up the MCP server, and telling Sonar where it is. Neither Node.js nor Chromium is installed on the Sonar host.

Follow the steps in order.

1. Install the File Store app, if it is not installed already.
2. Stand up a Playwright MCP server - Linux or Windows, below.
3. Register the server in Sonar, as a connect profile or a system property.
4. Register a credential profile for each site that requires a sign-in. Sites that need no account require nothing here.

Scope

Requirements

Installing the MCP server on Linux

Docker is recommended: the image already carries Chromium and the shared libraries it needs, which is the part that otherwise requires root-level package installation.

docker run -d --name playwright-mcp --restart unless-stopped \
  -p 8931:8931 \
  mcr.microsoft.com/playwright/mcp \
  --port 8931 --host 0.0.0.0 --allowed-hosts sonar-host \
  --headless --isolated \
  --ignore-https-errors --output-dir /tmp/playwright-mcp

Replace sonar-host with the hostname or address the Sonar host will use to reach this server. See Host header verification below - this is the option most installations get wrong.

Without Docker, install Node.js LTS and run the server directly. Chromium's shared library dependencies must be satisfied on the host, which on a minimal image means installing them first.

npx --yes @playwright/mcp@latest install chromium
npx --yes @playwright/mcp@latest --port 8931 --host 0.0.0.0 \
  --allowed-hosts sonar-host --headless --isolated \
  --ignore-https-errors --output-dir /var/lib/playwright-mcp

For continuous operation, register it as a systemd unit rather than leaving it in a shell.

Installing the MCP server on Windows

There is no Docker step here. Windows Chromium carries the libraries it needs, so no administrator-level package installation is involved.

# 1) With Node.js LTS installed, fetch the browser
npx --yes @playwright/mcp@latest install chromium

# 2) Run the server
npx --yes @playwright/mcp@latest --port 8931 --host 0.0.0.0 --allowed-hosts sonar-host --headless --isolated --ignore-https-errors --output-dir C:\playwright-mcp

For continuous operation, register it as a Windows service - for example with NSSM:

nssm install playwright-mcp "C:\Program Files\nodejs\npx.cmd" "--yes @playwright/mcp@latest --port 8931 --host 0.0.0.0 --allowed-hosts sonar-host --headless --isolated --ignore-https-errors --output-dir C:\playwright-mcp"
nssm start playwright-mcp

Server options

Host header verification

The server checks the Host header, and by default only accepts the hostname it was bound to. --host 0.0.0.0 alone is not enough: a server started that way answers Access is denied (HTTP 403) when reached by IP address, while localhost passes. List the hosts that will connect:

--host 0.0.0.0 --allowed-hosts sonar-host,100.64.0.30

Setting --allowed-hosts to a single asterisk disables the check, but it exists to defend against DNS rebinding, so naming the hosts is preferable.

Security

Registering the server in Sonar

There are two ways, and with either one a command does not have to name the server.

Connect profile

Go to System > Connect Profiles, click Add, and select the Playwright MCP Server type.

When exactly one server is registered, commands use it without naming it. Name one with the mcp option only when several are registered.

Test Connect checks that the server answers and that it really is a Playwright MCP server. It opens no site.

System property

A server address can be set without creating a profile at all.

playwright.server.url=http://playwright-host:8931/mcp

The PLAYWRIGHT_SERVER_URL environment variable does the same. A registered profile takes precedence. With none of the three set, commands refuse and say so.

Registering a credential profile

Only for sites that require a sign-in. Go to System > Connect Profiles, click Add, and select the Playwright Credential type.

The password and the TOTP seed are encrypted by the platform. This profile holds neither a site address nor a server address - a command names the site with url and the server with mcp, which is what lets one account be used on every address it applies to.

Verifying the installation

Open a site that needs no account and read the screen. If a snapshot comes back, the server and the network path are working; take a screenshot as well to confirm the file store is.

playwright-open url="https://www.example.com/"
playwright-observe session-id="SESSION_ID"
playwright-screenshot session-id="SESSION_ID"
playwright-close session-id="SESSION_ID"

playwright-open returns the session_id the other commands take.

A session holds a browser on the shared server until it is closed or reaped for being idle, so close it when done.

Version pinning

Tool names and schemas can change between server versions. In production, pin @playwright/mcp@VERSION or a tagged Docker image, and after an upgrade use the MCP profile's connect test to confirm the browser_* tools are still present.

Air-gapped installation

# On a connected host
docker pull mcr.microsoft.com/playwright/mcp
docker save mcr.microsoft.com/playwright/mcp -o playwright-mcp.tar

# On the air-gapped host
docker load -i playwright-mcp.tar

Without Docker, carry in Node.js, the @playwright/mcp npm package, and the output of playwright install chromium (~/.cache/ms-playwright on Linux, %USERPROFILE%\AppData\Local\ms-playwright on Windows).

References

• Logpresso Sonar documentation
• Connect profile configuration guide
• Playwright MCP