Configuration¶

Use upstream PLAYWRIGHT_MCP_* variables for Playwright MCP behavior. Use CLOAK_PLAYWRIGHT_MCP_* only for Cloak-specific bridge behavior.

The old CLOAKBROWSER_MCP_* variables are not supported. The generated CLI Reference is the authoritative list of bridge CLI flags and their matching environment variables. For task-focused examples, see the Recipes section.

Bridge Options¶

GeoIP Proxy Matching¶

Set CLOAK_PLAYWRIGHT_MCP_GEOIP_PROXY_MATCH=true with PLAYWRIGHT_MCP_PROXY_SERVER to derive CloakBrowser timezone, language, and locale fingerprint flags from the proxy location. The bridge keeps proxy routing delegated to upstream Playwright MCP and only injects the resolved --fingerprint-timezone, --lang, and --fingerprint-locale launch flags.

See GeoIP Proxy Matching for setup examples, runtime Streamable HTTP proxy metadata, use cases, precedence rules, and limitations. For a concise task path, see Regional QA Through Proxy.

Humanized Input Behavior¶

Set CLOAK_PLAYWRIGHT_MCP_HUMANIZE=true to enable CloakBrowser's human-like mouse, keyboard, and scroll layer for page interactions. The bridge applies this through Playwright MCP's page initialization hook, so upstream browser tool schemas stay unchanged.

See Humanized Input Behavior for setup examples, runtime Streamable HTTP metadata, use cases, and limitations.

Chrome Extensions¶

Chrome extensions are loaded when the browser starts, so configure them before starting the bridge or before creating a Streamable HTTP session. Extensions must be unpacked directories and require a persistent profile:

PLAYWRIGHT_MCP_USER_DATA_DIR="$PWD/.profiles/default" \
  CLOAK_PLAYWRIGHT_MCP_EXTENSION_PATHS='["/absolute/path/to/my-extension"]' \
  npx -y cloakbrowser-mcp@latest

For Streamable HTTP, pass the profile and extension directories in initialize metadata:

{
  "params": {
    "_meta": {
      "io.github.swimmwatch/cloakbrowser-mcp": {
        "userDataDir": "/absolute/path/to/profile",
        "extensionPaths": ["/absolute/path/to/my-extension"]
      }
    }
  }
}

Restart the bridge or create a new HTTP session after changing extension files or extension paths. Use a JSON array for CLOAK_PLAYWRIGHT_MCP_EXTENSION_PATHS when paths contain commas, when passing multiple extensions, or when using Windows drive-letter paths.

See Load Chrome Extension for a shorter copy-paste setup.

Streamable HTTP Runtime Metadata¶

Streamable HTTP clients can choose selected runtime options per MCP session by adding bridge-specific metadata to the initialize request:

{
  "params": {
    "_meta": {
      "io.github.swimmwatch/cloakbrowser-mcp": {
        "proxyServer": "http://user:pass@proxy.example:8080",
        "proxyBypass": ".internal,localhost",
        "geoipProxyMatch": true,
        "headless": false,
        "humanize": true,
        "humanPreset": "careful",
        "userDataDir": "/absolute/path/to/profile",
        "contextOptions": {
          "viewport": { "width": 1280, "height": 720 },
          "locale": "en-US",
          "timezoneId": "America/New_York"
        },
        "extensionPaths": ["/absolute/path/to/extension"]
      }
    }
  }
}

proxyServer overrides PLAYWRIGHT_MCP_PROXY_SERVER for that HTTP session. proxyBypass overrides PLAYWRIGHT_MCP_PROXY_BYPASS only when proxyServer is present. geoipProxyMatch can enable or disable GeoIP matching for that session without restarting the MCP server. Existing sessions keep their startup proxy; create a new HTTP session to switch location.

humanize can enable or disable humanized input behavior for that session without changing other sessions. humanPreset can select default or careful for that session, but does not enable humanized behavior by itself. Existing sessions keep the behavior captured during initialize.

headless can enable or disable headless browser mode for that session. Setting headless to false requires a usable display environment, especially in Docker or Linux server deployments.

userDataDir enables a persistent Chromium profile for that session and overrides PLAYWRIGHT_MCP_USER_DATA_DIR. The bridge resolves the directory to an absolute platform-native path, creates it if missing, verifies it is writable, and writes it to generated browser.userDataDir. A persistent profile disables the default Streamable HTTP isolated profile for that session. The bridge rejects duplicate active profile directories inside one process; cross-process profile conflicts remain Chromium/Playwright errors.

contextOptions are validated and shallow-merged over CLOAK_PLAYWRIGHT_MCP_CONTEXT_OPTIONS; nested objects replace whole values. Supported fields are userAgent, viewport, locale, timezoneId, colorScheme, permissions, geolocation, extraHTTPHeaders, httpCredentials, ignoreHTTPSErrors, offline, deviceScaleFactor, isMobile, and hasTouch. Arbitrary BrowserContextOptions passthrough is not supported in this release.

extensionPaths must point to existing directories and require a persistent userDataDir. The bridge resolves extension paths to absolute platform-native paths, passes them to CloakBrowser, and writes the generated --load-extension and --disable-extensions-except Chromium arguments into the generated Playwright MCP config.

Authenticated HTTP proxy credentials can be embedded in proxyServer, for example http://user:pass@proxy.example:8080. Percent-encode credential characters that have URL meaning, such as @, :, /, ?, #, and %.

For multi-location QA patterns, see GeoIP Proxy Matching. For interaction realism patterns, see Humanized Input Behavior. For login reuse and extension setup, see Persistent Login Profile and Load Chrome Extension.

Upstream Options¶

The bridge forwards PLAYWRIGHT_MCP_* settings to upstream Playwright MCP. That includes upstream options such as:

• PLAYWRIGHT_MCP_ALLOWED_ORIGINS
• PLAYWRIGHT_MCP_BLOCKED_ORIGINS
• PLAYWRIGHT_MCP_ALLOW_UNRESTRICTED_FILE_ACCESS
• PLAYWRIGHT_MCP_CAPS
• PLAYWRIGHT_MCP_CONSOLE_LEVEL
• PLAYWRIGHT_MCP_IMAGE_RESPONSES
• PLAYWRIGHT_MCP_SNAPSHOT_MODE
• PLAYWRIGHT_MCP_STORAGE_STATE

Refer to the upstream Playwright MCP documentation for the full upstream option surface.

Logging¶

Streamable HTTP mode writes human-readable startup and request logs to stdout. Stdio mode does not emit routine operational logs so MCP JSON-RPC stdout remains protocol-clean. Fatal CLI startup failures are still written to stderr.

HTTPS¶

Streamable HTTP uses local HTTP by default. Select direct TLS with --http-protocol https or CLOAK_PLAYWRIGHT_MCP_HTTP_PROTOCOL=https, then provide either a certificate/key pair or a PFX file:

cloakbrowser-mcp --transport streamable-http \
  --http-protocol https \
  --https-cert ./cert.pem \
  --https-key ./key.pem

For external or non-loopback exposure, use HTTPS plus --http-auth-token, or terminate TLS at a trusted reverse proxy that also enforces authentication and network access controls.

Streamable HTTP Sessions¶

Each Streamable HTTP MCP session owns its own bridge runtime and upstream Playwright MCP child process. HTTP sessions run upstream Playwright MCP with an isolated browser profile so concurrent users do not contend for the same persistent Chromium profile. The built-in memory session backend stores only metadata such as session ID, timestamps, expiry, and status. Browser state remains in the live upstream child process, and artifacts are still controlled by PLAYWRIGHT_MCP_OUTPUT_DIR.

For horizontal scaling, run multiple server replicas behind a load balancer with sticky sessions keyed by the mcp-session-id header. Future Redis, Postgres, or SQLite backends can coordinate metadata and locks, but they cannot restore a live browser session after the process that owns it exits.

Streamable HTTP Probes¶

When the bridge runs with --transport streamable-http, it exposes fixed probe endpoints on the same host and port as the MCP endpoint:

• GET /healthz returns process health metadata: status, version, transport, and uptimeMs.
• GET /readyz returns readiness metadata and session capacity: sessions.active, sessions.pending, sessions.max, and sessions.available.

Readiness returns HTTP 200 while session capacity is available and HTTP 503 when active + pending >= max. If --http-auth-token or CLOAK_PLAYWRIGHT_MCP_HTTP_AUTH_TOKEN is configured, both probes require the same Authorization: Bearer ... header as MCP requests. Without an auth token, the probes are open on the configured HTTP bind address.