From 85c19589924bae4ed1d9c0606b11427ab34947ce Mon Sep 17 00:00:00 2001 From: dprevoznik <58714078+dprevoznik@users.noreply.github.com> Date: Tue, 21 Jul 2026 02:35:24 +0000 Subject: [PATCH 1/5] docs(mcp): require session_id for execute_playwright_code; add manage_replays MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit execute_playwright_code no longer creates/deletes browsers or returns a replay_url — it's a passthrough that requires an existing session_id. Document the new manage_replays tool (start/stop/list) and point lifecycle at manage_browsers. Co-Authored-By: Claude Opus 4.8 --- browsers/playwright-execution.mdx | 2 +- docs.json | 1 + reference/mcp-server/examples.mdx | 18 +++++++-- .../tools/execute-playwright-code.mdx | 12 ++++-- .../mcp-server/tools/manage-browsers.mdx | 2 + reference/mcp-server/tools/manage-replays.mdx | 38 +++++++++++++++++++ 6 files changed, 65 insertions(+), 8 deletions(-) create mode 100644 reference/mcp-server/tools/manage-replays.mdx diff --git a/browsers/playwright-execution.mdx b/browsers/playwright-execution.mdx index fd05c767..20c13edc 100644 --- a/browsers/playwright-execution.mdx +++ b/browsers/playwright-execution.mdx @@ -353,4 +353,4 @@ This makes it ideal for one-off operations where you need maximum speed. ## MCP server integration -This feature is available as a tool in our [MCP server](/reference/mcp-server). AI agents can use the `execute_playwright_code` tool to run Playwright code against browsers with automatic video replay and cleanup. +This feature is available as a tool in our [MCP server](/reference/mcp-server). AI agents create a session with the `manage_browsers` tool, run Playwright code against it with the `execute_playwright_code` tool, and can capture a video with the `manage_replays` tool. diff --git a/docs.json b/docs.json index d04309b4..fd5ca1ac 100644 --- a/docs.json +++ b/docs.json @@ -337,6 +337,7 @@ "reference/mcp-server/tools/manage-apps", "reference/mcp-server/tools/computer-action", "reference/mcp-server/tools/execute-playwright-code", + "reference/mcp-server/tools/manage-replays", "reference/mcp-server/tools/exec-command", "reference/mcp-server/tools/search-docs" ] diff --git a/reference/mcp-server/examples.mdx b/reference/mcp-server/examples.mdx index 0b779cdb..11a99571 100644 --- a/reference/mcp-server/examples.mdx +++ b/reference/mcp-server/examples.mdx @@ -15,9 +15,21 @@ Assistant: I'll execute your web-scraper action with reddit.com as the target. ``` Human: Go to example.com and get me the page title -Assistant: I'll execute Playwright code to navigate to the site and retrieve the title. -[Uses execute_playwright_code tool with code: "await page.goto('https://example.com'); return await page.title();"] -Returns: { success: true, result: "Example Domain", replay_url: "https://..." } +Assistant: I'll create a browser session, then execute Playwright code to navigate to the site and retrieve the title. +[Uses manage_browsers tool with action: "create" to launch a session] +[Uses execute_playwright_code tool with session_id and code: "await page.goto('https://example.com'); return await page.title();"] +Returns: { success: true, result: "Example Domain" } +[Uses manage_browsers tool with action: "delete" to clean up the session] +``` + +## Record a video replay of an automation + +``` +Human: Record a video while you scrape this page +Assistant: I'll start a replay recording, run the automation, then stop it. +[Uses manage_replays tool with action: "start" and the session_id] +[Uses execute_playwright_code tool to run the automation] +[Uses manage_replays tool with action: "stop" to end the recording] ``` ## Set up browser profiles for authentication diff --git a/reference/mcp-server/tools/execute-playwright-code.mdx b/reference/mcp-server/tools/execute-playwright-code.mdx index 71525153..6f88fd6b 100644 --- a/reference/mcp-server/tools/execute-playwright-code.mdx +++ b/reference/mcp-server/tools/execute-playwright-code.mdx @@ -3,7 +3,9 @@ title: "execute_playwright_code" description: "Run Playwright/TypeScript code against a browser session" --- -Execute Playwright/TypeScript automation code against a Kernel browser session. If `session_id` is provided, uses that existing browser; otherwise creates a new one. Returns the result with a video replay URL, and auto-cleans up browsers it creates. +Execute Playwright/TypeScript automation code against an existing Kernel browser session. This tool is a thin passthrough: it runs your code in the browser's VM and returns the result. It does not manage browser lifecycle — create and delete sessions with [`manage_browsers`](/reference/mcp-server/tools/manage-browsers). + +`session_id` is required. Unlike earlier versions, this tool no longer creates a browser when `session_id` is omitted, and no longer deletes the browser after execution. Create a session with `manage_browsers` (action `create`), pass its `session_id` here, then delete it with `manage_browsers` when done. Use `computer_action` with the `screenshot` action instead of `page.screenshot()` in your code. For a comprehensive page state snapshot, use `await page._snapshotForAI()`. @@ -12,12 +14,13 @@ Execute Playwright/TypeScript automation code against a Kernel browser session. | Parameter | Description | |-----------|-------------| | `code` | Playwright/TypeScript code with a `page` object in scope. Required. | -| `session_id` | Existing browser session ID. If omitted, a new browser is created and cleaned up after execution. | +| `session_id` | Existing browser session ID to run against. Required. | ## Example ```json { + "session_id": "session_abc123", "code": "await page.goto('https://example.com'); return await page.title();" } ``` @@ -27,7 +30,8 @@ Returns: ```json { "success": true, - "result": "Example Domain", - "replay_url": "https://..." + "result": "Example Domain" } ``` + +To capture a video recording around your automation, start a recording with [`manage_replays`](/reference/mcp-server/tools/manage-replays) before your calls and stop it when done. diff --git a/reference/mcp-server/tools/manage-browsers.mdx b/reference/mcp-server/tools/manage-browsers.mdx index 5cf3816d..30ba2d24 100644 --- a/reference/mcp-server/tools/manage-browsers.mdx +++ b/reference/mcp-server/tools/manage-browsers.mdx @@ -5,6 +5,8 @@ description: "Create, list, get, and delete browser sessions" Manage browser sessions on the Kernel platform. Created browsers run in isolated VMs and support headless/stealth modes, profiles, proxies, viewports, extensions, and SSH tunneling. +Browser lifecycle lives here: `create` a session before running [`execute_playwright_code`](/reference/mcp-server/tools/execute-playwright-code) against it, and `delete` it when you're done. + ## Actions | Action | Description | diff --git a/reference/mcp-server/tools/manage-replays.mdx b/reference/mcp-server/tools/manage-replays.mdx new file mode 100644 index 00000000..f00172d5 --- /dev/null +++ b/reference/mcp-server/tools/manage-replays.mdx @@ -0,0 +1,38 @@ +--- +title: "manage_replays" +description: "Start, stop, and list video replay recordings for a browser session" +--- + +Record video replays of a browser session. Recording is opt-in and session-scoped: start a recording once, run your automation (for example with [`execute_playwright_code`](/reference/mcp-server/tools/execute-playwright-code)), then stop it — rather than recording each call separately. + +Replays require a headful session. They are not available for [headless](/browsers/headless) browsers. + +## Actions + +| Action | Description | +|--------|-------------| +| `start` | Begin recording a session. Returns a `replay_id`. | +| `stop` | Stop a recording. | +| `list` | List recordings for a session, including their view/download URLs. | + +## Parameters + +| Parameter | Description | +|-----------|-------------| +| `action` | Operation to perform: `start`, `stop`, or `list`. Required. | +| `session_id` | Browser session ID. Required. | +| `replay_id` | Recording ID to stop. Required for `stop`. | +| `framerate` | (start) Frames per second for the recording. | +| `max_duration_in_seconds` | (start) Maximum recording length in seconds. | +| `record_audio` | (start) Capture audio in addition to video. | + +## Example + +```json +{ + "action": "start", + "session_id": "session_abc123", + "framerate": 30, + "max_duration_in_seconds": 300 +} +``` From d56f4a20de578f60c36f9a1848660592b1796ca5 Mon Sep 17 00:00:00 2001 From: dprevoznik <58714078+dprevoznik@users.noreply.github.com> Date: Tue, 21 Jul 2026 02:39:29 +0000 Subject: [PATCH 2/5] docs(mcp): trim manage_replays description Co-Authored-By: Claude Opus 4.8 --- reference/mcp-server/tools/manage-replays.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/mcp-server/tools/manage-replays.mdx b/reference/mcp-server/tools/manage-replays.mdx index f00172d5..f65ba545 100644 --- a/reference/mcp-server/tools/manage-replays.mdx +++ b/reference/mcp-server/tools/manage-replays.mdx @@ -3,7 +3,7 @@ title: "manage_replays" description: "Start, stop, and list video replay recordings for a browser session" --- -Record video replays of a browser session. Recording is opt-in and session-scoped: start a recording once, run your automation (for example with [`execute_playwright_code`](/reference/mcp-server/tools/execute-playwright-code)), then stop it — rather than recording each call separately. +Record video replays of a browser session. Recording is opt-in and session-scoped: start a recording once, run your automation (for example with [`execute_playwright_code`](/reference/mcp-server/tools/execute-playwright-code)), then stop it. Replays require a headful session. They are not available for [headless](/browsers/headless) browsers. From 2c570181ad50f609874e1e172f7db70f80a85d2e Mon Sep 17 00:00:00 2001 From: dprevoznik <58714078+dprevoznik@users.noreply.github.com> Date: Tue, 21 Jul 2026 02:40:13 +0000 Subject: [PATCH 3/5] docs(mcp): drop framerate from manage_replays example Co-Authored-By: Claude Opus 4.8 --- reference/mcp-server/tools/manage-replays.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/reference/mcp-server/tools/manage-replays.mdx b/reference/mcp-server/tools/manage-replays.mdx index f65ba545..2c8f0df7 100644 --- a/reference/mcp-server/tools/manage-replays.mdx +++ b/reference/mcp-server/tools/manage-replays.mdx @@ -32,7 +32,6 @@ Record video replays of a browser session. Recording is opt-in and session-scope { "action": "start", "session_id": "session_abc123", - "framerate": 30, "max_duration_in_seconds": 300 } ``` From 23fd33366ffde4cd736c8595026658839c9d6ae1 Mon Sep 17 00:00:00 2001 From: dprevoznik <58714078+dprevoznik@users.noreply.github.com> Date: Tue, 21 Jul 2026 02:46:49 +0000 Subject: [PATCH 4/5] docs(mcp): use a bullet list for the MCP workflow steps Co-Authored-By: Claude Opus 4.8 --- browsers/playwright-execution.mdx | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/browsers/playwright-execution.mdx b/browsers/playwright-execution.mdx index 20c13edc..9d016e1a 100644 --- a/browsers/playwright-execution.mdx +++ b/browsers/playwright-execution.mdx @@ -353,4 +353,8 @@ This makes it ideal for one-off operations where you need maximum speed. ## MCP server integration -This feature is available as a tool in our [MCP server](/reference/mcp-server). AI agents create a session with the `manage_browsers` tool, run Playwright code against it with the `execute_playwright_code` tool, and can capture a video with the `manage_replays` tool. +This feature is available as a tool in our [MCP server](/reference/mcp-server). AI agents drive it across three tools: + +- `manage_browsers` — create a session (and delete it when done). +- `execute_playwright_code` — run Playwright code against that session. +- `manage_replays` — optionally record a video while the automation runs. From d36173fe0a7970fba4db074fb436239d719465f4 Mon Sep 17 00:00:00 2001 From: dprevoznik <58714078+dprevoznik@users.noreply.github.com> Date: Tue, 21 Jul 2026 02:49:51 +0000 Subject: [PATCH 5/5] docs(mcp): simplify MCP integration blurb in playwright-execution Co-Authored-By: Claude Opus 4.8 --- browsers/playwright-execution.mdx | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/browsers/playwright-execution.mdx b/browsers/playwright-execution.mdx index 9d016e1a..a2d72057 100644 --- a/browsers/playwright-execution.mdx +++ b/browsers/playwright-execution.mdx @@ -353,8 +353,4 @@ This makes it ideal for one-off operations where you need maximum speed. ## MCP server integration -This feature is available as a tool in our [MCP server](/reference/mcp-server). AI agents drive it across three tools: - -- `manage_browsers` — create a session (and delete it when done). -- `execute_playwright_code` — run Playwright code against that session. -- `manage_replays` — optionally record a video while the automation runs. +This feature is available as a tool in our [MCP server](/reference/mcp-server). AI agents can use the `execute_playwright_code` tool to run Playwright code against browsers directly in the VM with lower latency.