Playwright MCP

When to Use

• Browsing websites or testing UI in a headless browser
• Navigating to authenticated pages (e.g., uvilo.ai, os.uvilo.com)
• Taking screenshots of web pages

Procedure

1. Accessing the Playwright MCP

The Playwright MCP server is a deferred tool. Use ToolSearch to load it if not already available.

It runs as a separate Railway service (serverless, 5–15s cold start).

2. Transport

Uses the SSE endpoint (/sse). Do NOT use streamable-http (/mcp).

The streamable-http transport has a hardcoded 5-second heartbeat timeout in the Playwright MCP server. When an LLM takes >5s between tool calls (e.g., navigate → snapshot), the heartbeat times out, the session is killed, and the client reconnects with a new session that starts at about:blank. The SSE transport has no heartbeat timeout and keeps sessions alive indefinitely.

Upstream issues: microsoft/playwright-mcp#1293, #1307, #1140.

3. Allowed Hosts

The Docker image has two network controls: --host (bind address) and --allowed-hosts (access control list). Even bound to 0.0.0.0, non-localhost connections are rejected unless --allowed-hosts * is set.

Critical: The env var is PLAYWRIGHT_MCP_ALLOWED_HOSTNAMES (not HOSTS — the README is wrong). Using the wrong name silently fails — server starts but rejects connections with 403.

PLAYWRIGHT_MCP_ALLOWED_HOSTNAMES is a Railway env var consumed by the MCP server process itself. The agent never reads it — no /proc/1/environ export needed.

4. Authenticated Browsing

Credentials for sites the assistant can log into come from environment variables on the forgentic container or approved MCP/tool configuration. Check available credentials before navigating to a login page.

If credentials for a site are not available, ask the user to provide them or create the account.

OAuth/SSO-only sites cannot be logged into — use API-based MCP tools instead.

5. Vercel Deployment Protection Bypass

Sites behind Vercel deployment protection (e.g., os.uvilo.com) require a bypass secret. The bypass token is available from the VERCEL_PROTECTION_BYPASS environment variable on the forgentic container.

Always include both query parameters on the first navigation:

https://os.uvilo.com/?x-vercel-protection-bypass=<secret>&x-vercel-set-bypass-cookie=samesitenone

This authenticates the initial HTML request tells Vercel to set a cookie so all subsequent requests (CSS, JS, images under /_astro/*) also bypass protection.

Gotchas

• Session timeout bug (streamable-http): The /mcp endpoint kills sessions after 5s idle. Always use /sse instead. See Transport section above.
• Wrong env var name (HOSTS vs HOSTNAMES) causes silent 403 failures
• Serverless mode means first call after idle may take 5–15s
• No OAuth/SSO login support — use API tools for those sites
• Vercel bypass without x-vercel-set-bypass-cookie breaks static assets