Browser Tools: Playwright Automation and CDP Attach

Browser tools drive automated browser sessions using Playwright and additionally support attaching to an existing Chrome or Edge instance via the Chrome DevTools Protocol (CDP). All 16 tools require the mcp:browser scope. Sessions are isolated by default — each browser_session_create call launches a fresh browser process with no pre-existing cookies, local storage, or login state. CDP attach is the escape hatch for cases where an already-authenticated profile is required.

Prerequisite: Playwright browser binaries

Before using any browser tool, the Playwright browser binaries must be installed on the host:

npx playwright install

Without this step, browser_session_create will fail with a missing executable error. Reinstall after upgrading the package.

Session limits

Configuration variable	Default	Description
`GPT_FS_MCP_BROWSER_SESSION_IDLE_MS`	`1800000` (30 min)	Sessions inactive for this duration are automatically closed.
`GPT_FS_MCP_MAX_BROWSER_SESSIONS`	`5`	Maximum number of concurrent browser sessions.

When the session limit is reached, the oldest idle session is evicted before a new one can be created. Screenshot files are pruned according to GPT_FS_MCP_MAX_BROWSER_SCREENSHOT_FILES and GPT_FS_MCP_MAX_BROWSER_SCREENSHOT_BYTES.

Session management tools

1. `browser_session_create`

Attribute	Value
Required scope	`mcp:browser`
Policy mode	`operate`

Preferred browser entry point. Creates a new isolated Playwright browser session. Use this instead of browser_cdp_connect unless you explicitly need an existing logged-in profile. Parameters

Parameter	Type	Default	Description
`browser`	`"chromium" \| "firefox" \| "webkit"`	`"chromium"`	Browser engine to launch.
`url`	`string` (URL)	—	Optional initial URL to navigate to after launch.
`headless`	`boolean`	`false`	Run without a visible browser window.
`allowNonHttp`	`boolean`	`false`	Allow non-http/https URLs (requires `confirm: true`).
`allowedHostnames`	`string[]`	`[]`	Immutable host allowlist for this session. Supports exact hostnames and `*.example.com` wildcards. Navigations and interactions outside this list are blocked.
`viewportWidth`	`number`	`1440`	Viewport width in pixels (max 7680).
`viewportHeight`	`number`	`900`	Viewport height in pixels (max 4320).
`timeoutMs`	`number`	`30000`	Launch and navigation timeout in milliseconds (max 120,000).
`confirm`	`boolean`	`false`	Required when `url` uses a non-http scheme and `allowNonHttp` is `true`.

Response fields: sessionId, browser, source ("isolated"), headless, url, title, createdAt, lastUsedAt, allowedHostnames.

2. `browser_session_list`

Attribute	Value
Required scope	`mcp:browser`
Policy mode	`observe`

Lists all currently active Playwright browser sessions, including their IDs, current page URL, title, browser type, and idle timeout status. Idle sessions are cleaned up automatically before the list is returned. Parameters: none. Response fields: sessions (array of session summaries).

3. `browser_session_close`

Attribute	Value
Required scope	`mcp:browser`
Policy mode	`operate`

Closes a browser session and releases the underlying browser process and all associated resources. Always close sessions when you are done to avoid hitting the concurrent session limit. Parameters

Parameter	Type	Description
`sessionId`	`string` (UUID)	Session ID returned by session create.

Response fields: closed (boolean), sessionId.

4. `browser_cdp_connect`

Attribute	Value
Required scope	`mcp:browser`
Policy mode	`operate`
Risk tags	`browser`, `cdp`, `existing-profile`, `secret-read`

CDP attach connects to an existing Chrome or Edge browser instance, including its active login sessions, stored cookies, and open tabs. It can interact with authenticated sites (banking, email, SaaS dashboards) using credentials you never explicitly provided. Use a dedicated browser profile and never attach to a profile with sensitive accounts unless you are willing to expose those sessions. Requires confirm: true.

Attaches to a Chromium-based browser that has been started with --remote-debugging-port. Use this only when an already-authenticated profile or specific existing tab state is required and cannot be reproduced in an isolated session. Parameters

Parameter	Type	Default	Description
`endpointUrl`	`string`	`"http://127.0.0.1:9222"`	CDP HTTP or WebSocket endpoint URL.
`confirm`	`boolean`	`false`	Required — must be `true` to attach.
`allowRemote`	`boolean`	`false`	Allow non-loopback CDP endpoints. Requires `confirm: true`.
`isolatedBrowserBypassReason`	`string`	(required)	Explain why `browser_session_create` is not sufficient. Logged for audit.
`purpose`	`string`	(required)	Short operational purpose for attaching to an existing profile.
`pageIndex`	`number`	`0`	Which existing page/tab to select as the active page.
`allowedHostnames`	`string[]`	`[]`	Immutable host allowlist for this CDP session.
`timeoutMs`	`number`	`30000`	Connection timeout in milliseconds.

Response fields: sessionId, source ("cdp"), cdpEndpoint, pages (list of all open tabs), auditQuality ("sensitive").

5. `browser_navigate`

Attribute	Value
Required scope	`mcp:browser`
Policy mode	`operate`

Navigates the active page in a session to a new URL. If allowedHostnames was set on the session, the target URL is checked before navigation begins. Out-of-scope popup pages opened during navigation are automatically closed. Parameters

Parameter	Type	Default	Description
`sessionId`	`string` (UUID)	(required)	Target session.
`url`	`string` (URL)	(required)	URL to navigate to.
`waitUntil`	`"commit" \| "domcontentloaded" \| "load" \| "networkidle"`	`"domcontentloaded"`	When to consider navigation complete.
`allowNonHttp`	`boolean`	`false`	Allow non-http/https URLs (requires `confirm: true`).
`confirm`	`boolean`	`false`	Required for non-http URLs or CDP session navigations.
`timeoutMs`	`number`	`30000`	Navigation timeout in milliseconds.

6. `browser_page_list`

Attribute	Value
Required scope	`mcp:browser`
Policy mode	`observe`

Lists all open pages (tabs) in a browser session. Each entry includes the page index, URL, title, whether it is the currently active page, and whether it is outside the session’s allowedHostnames. Parameters

Parameter	Type	Default	Description
`sessionId`	`string` (UUID)	(required)	Target session.
`raw`	`boolean`	`false`	Return unredacted URLs and titles (requires `confirm: true`).
`confirm`	`boolean`	`false`	Required when `raw: true`.

7. `browser_page_select`

Attribute	Value
Required scope	`mcp:browser`
Policy mode	`operate`

Makes a different page the active page in the session. Use the pageIndex from browser_page_list. If the target page’s URL is outside the session’s allowedHostnames, the selection is rejected (and the page is closed). Parameters

Parameter	Type	Description
`sessionId`	`string` (UUID)	Target session.
`pageIndex`	`number`	Zero-based page index from `browser_page_list`.

8. `browser_snapshot`

Attribute	Value
Required scope	`mcp:browser`
Policy mode	`observe`

Preferred structured read of a web page. Returns an ARIA accessibility tree snapshot of the current page, optimized for AI consumption. Use this before performing element interactions and prefer it over screenshots unless you specifically need to inspect pixels or visual layout. Parameters

Parameter	Type	Default	Description
`sessionId`	`string` (UUID)	(required)	Target session.
`depth`	`number`	`8`	Maximum ARIA tree depth (max 20).
`boxes`	`boolean`	`false`	Include bounding boxes for each ARIA node.
`maxBytes`	`number`	—	Truncate snapshot output to this many bytes.
`raw`	`boolean`	`false`	Return unredacted snapshot content (requires `confirm: true`).
`confirm`	`boolean`	`false`	Required when `raw: true`.

Response fields: ariaSnapshot, url, title, truncated, sourceTrust ("untrusted_external_content"), instructionSafety.

9. `browser_wait`

Attribute	Value
Required scope	`mcp:browser`
Policy mode	`diagnose`

Waits for a condition in the current page before proceeding. You can wait for a fixed time, a CSS selector to appear, a load state, or the URL to contain a specific string. Parameters

Parameter	Type	Default	Description
`sessionId`	`string` (UUID)	(required)	Target session.
`waitMs`	`number`	—	Wait a fixed number of milliseconds (max 60,000).
`loadState`	`"domcontentloaded" \| "load" \| "networkidle"`	—	Wait for a Playwright load state.
`selector`	`string`	—	Wait until a CSS selector is visible.
`urlIncludes`	`string`	—	Wait until the page URL contains this string.
`timeoutMs`	`number`	`30000`	Maximum time to wait in milliseconds.

Interaction tools

10. `browser_click`

Attribute	Value
Required scope	`mcp:browser`
Policy mode	`operate`

Clicks an element identified by CSS selector or an ARIA snapshot ariaRef. Prefer ariaRef from browser_snapshot when available — it is more stable than CSS selectors. On CDP sessions, requires confirm: true. Parameters

Parameter	Type	Default	Description
`sessionId`	`string` (UUID)	(required)	Target session.
`selector`	`string`	—	CSS selector for the target element.
`ariaRef`	`string`	—	ARIA ref from `browser_snapshot` (preferred over `selector`).
`purpose`	`string`	(required)	Short description of why this click is being performed.
`targetDescription`	`string`	(required)	Human-readable description of the element being clicked.
`expectedNavigationOrMutation`	`string`	—	Expected page change or no-op following the click.
`confirm`	`boolean`	`false`	Required for CDP sessions.
`timeoutMs`	`number`	`30000`	Element wait timeout.

11. `browser_fill`

Attribute	Value
Required scope	`mcp:browser`
Policy mode	`operate`

Fills an input, textarea, or other editable element by replacing its entire value. Prefer this over browser_type when you want to set a complete value rather than type character by character. Parameters

Parameter	Type	Description
`sessionId`	`string`	Target session.
`value`	`string`	Text value to fill. Logged as `[REDACTED]` with length in journal.
`selector`	`string`	CSS selector.
`ariaRef`	`string`	ARIA ref from `browser_snapshot` (preferred).
`purpose`	`string`	Short operational purpose.
`targetDescription`	`string`	Human-readable target description.
`expectedNavigationOrMutation`	`string`	Expected outcome.
`confirm`	`boolean`	Required for CDP sessions.
`timeoutMs`	`number`	Element wait timeout.

12. `browser_type`

Attribute	Value
Required scope	`mcp:browser`
Policy mode	`operate`

Types text into an element character by character, simulating real keystroke events. Use browser_fill to replace an input value; use browser_type when the application responds to individual keystrokes (e.g. autocomplete fields). Parameters

Parameter	Type	Default	Description
`sessionId`	`string`	(required)	Target session.
`text`	`string`	(required)	Text to type character by character.
`selector`	`string`	—	CSS selector.
`ariaRef`	`string`	—	ARIA ref (preferred).
`delayMs`	`number`	`0`	Delay between keystrokes in milliseconds (0–1000).
`purpose`	`string`	(required)	Short operational purpose.
`targetDescription`	`string`	(required)	Human-readable target description.
`expectedNavigationOrMutation`	`string`	—	Expected outcome.
`confirm`	`boolean`	`false`	Required for CDP sessions.
`timeoutMs`	`number`	`30000`	Element wait timeout.

13. `browser_press_key`

Attribute	Value
Required scope	`mcp:browser`
Policy mode	`operate`

Presses a keyboard key in the active page. Use Playwright key names such as "Enter", "Escape", "Tab", "ArrowDown", or "F5". Prefer browser_click, browser_fill, or browser_type for semantic interactions when possible. Parameters

Parameter	Type	Description
`sessionId`	`string`	Target session.
`key`	`string`	Playwright key name (e.g. `"Enter"`, `"Escape"`).
`purpose`	`string`	Short operational purpose.
`targetDescription`	`string`	Human-readable description.
`expectedNavigationOrMutation`	`string`	Expected outcome.
`confirm`	`boolean`	Required for CDP sessions.
`timeoutMs`	`number`	Timeout for the key press.

Inspection tools

14. `browser_screenshot`

Attribute	Value
Required scope	`mcp:browser`
Policy mode	`diagnose`
Risk tags	`browser-content`, `secret-read`, `screenshot`

Captures a PNG screenshot of the current browser page and saves it to disk. Prefer browser_snapshot for DOM and ARIA understanding; use this tool when you need to inspect visual layout, rendering, or pixel-level details. Screenshots are stored in the server’s data directory and rotated based on the browser screenshot file limit. Parameters

Parameter	Type	Default	Description
`sessionId`	`string`	(required)	Target session.
`fullPage`	`boolean`	`false`	Capture the full scrollable page instead of just the visible viewport.
`includeImageBase64`	`boolean`	`false`	Include the PNG as a base64 string in the response (subject to output size limits).

Response fields: path, screenshotId, hash, size, sessionId, url, title, sourceTrust ("untrusted_external_content"), imageBase64?.

15. `browser_console`

Attribute	Value
Required scope	`mcp:browser`
Policy mode	`observe`

Returns recent console messages captured for a browser session since it was created or last used. URLs and sensitive-looking values in log text are redacted by default. Parameters

Parameter	Type	Default	Description
`sessionId`	`string`	(required)	Target session.
`limit`	`number`	`100`	Maximum number of most-recent entries to return (max 500).
`maxBytes`	`number`	—	Truncate output to this byte budget.
`raw`	`boolean`	`false`	Return unredacted log text (requires `confirm: true`).
`confirm`	`boolean`	`false`	Required when `raw: true`.

Response fields: entries (array of { type, text, location?, timestamp, textTruncated? }), truncated, totalBytes, sourceTrust.

16. `browser_network`

Attribute	Value
Required scope	`mcp:browser`
Policy mode	`observe`

Returns recent network response and request-failure events captured for a browser session. URLs containing auth parameters, tokens, and credentials are redacted by default. Parameters

Parameter	Type	Default	Description
`sessionId`	`string`	(required)	Target session.
`limit`	`number`	`100`	Maximum number of most-recent entries (max 500).
`maxBytes`	`number`	—	Truncate output to this byte budget.
`raw`	`boolean`	`false`	Return unredacted URLs (requires `confirm: true`).
`confirm`	`boolean`	`false`	Required when `raw: true`.

Response fields: entries (array of { type, method, url, status?, error?, timestamp }), truncated, totalBytes, sourceTrust.

CDP attach warning

browser_cdp_connect can interact with a browser that is already logged in to banking, email, cloud consoles, and other sensitive services. It can read page contents, fill forms, and click buttons on those pages using your existing session cookies — without you entering any credentials. Avoid attaching to a primary browser profile. Use a dedicated, isolated profile for MCP browser work whenever possible.

ChatGPT’s own safety layer may refuse to execute browser actions on authenticated sites regardless of server-side configuration. The allowedHostnames allowlist on a session is an additional server-side control, but it does not substitute for reviewing what the model is being asked to do.

Overview

Tools

Browser Tools: Playwright Automation and CDP Attach

Prerequisite: Playwright browser binaries

Session limits

Session management tools

1. `browser_session_create`

2. `browser_session_list`

3. `browser_session_close`

4. `browser_cdp_connect`

Navigation and page tools

5. `browser_navigate`

6. `browser_page_list`

7. `browser_page_select`

8. `browser_snapshot`

9. `browser_wait`

Interaction tools

10. `browser_click`

11. `browser_fill`

12. `browser_type`

13. `browser_press_key`

Inspection tools

14. `browser_screenshot`

15. `browser_console`

16. `browser_network`

CDP attach warning

See also

Build docs developers (and LLMs) love

Overview

Tools

Documentation Index

​Prerequisite: Playwright browser binaries

​Session limits

​Session management tools

​1. browser_session_create

​2. browser_session_list

​3. browser_session_close

​4. browser_cdp_connect

​Navigation and page tools

​5. browser_navigate

​6. browser_page_list

​7. browser_page_select

​8. browser_snapshot

​9. browser_wait

​Interaction tools

​10. browser_click

​11. browser_fill

​12. browser_type

​13. browser_press_key

​Inspection tools

​14. browser_screenshot

​15. browser_console

​16. browser_network

​CDP attach warning

​See also

Build docs developers (and LLMs) love

Prerequisite: Playwright browser binaries

Session limits

Session management tools

1. `browser_session_create`

2. `browser_session_list`

3. `browser_session_close`

4. `browser_cdp_connect`

Navigation and page tools

5. `browser_navigate`

6. `browser_page_list`

7. `browser_page_select`

8. `browser_snapshot`

9. `browser_wait`

Interaction tools

10. `browser_click`

11. `browser_fill`

12. `browser_type`

13. `browser_press_key`

Inspection tools

14. `browser_screenshot`

15. `browser_console`

16. `browser_network`

CDP attach warning

See also