@playwright/mcp 0.0.33 → 0.0.35-alpha-2025-08-27

package/README.md

@@ -56,6 +56,21 @@ Follow the MCP install [guide](https://modelcontextprotocol.io/quickstart/user),
 
 </details>
 
+<details>
+<summary>Codex</summary>
+
+Create or edit the configuration file `~/.codex/config.toml` and add:
+
+```toml
+[mcp_servers.playwright]
+command = "npx"
+args = ["@playwright/mcp@latest"]
+```
+
+For more information, see the [Codex MCP documentation](https://github.com/openai/codex/blob/main/codex-rs/config.md#mcp_servers).
+
+</details>
+
 <details>
 <summary>Cursor</summary>
 
@@ -100,6 +115,29 @@ Go to `Advanced settings` -> `Extensions` -> `Add custom extension`. Name to you
 Go to `Program` in the right sidebar -> `Install` -> `Edit mcp.json`. Use the standard config above.
 </details>
 
+<details>
+<summary>opencode</summary>
+
+Follow the MCP Servers [documentation](https://opencode.ai/docs/mcp-servers/). For example in `~/.config/opencode/opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "playwright": {
+      "type": "local",
+      "command": [
+        "npx",
+        "@playwright/mcp@latest"
+      ],
+      "enabled": true
+    }
+  }
+}
+
+```
+</details>
+
 <details>
 <summary>Qodo Gen</summary>
 
@@ -158,6 +196,9 @@ Playwright MCP server supports following arguments. They can be provided in the
   --config <path>              path to the configuration file.
   --device <device>            device to emulate, for example: "iPhone 15"
   --executable-path <path>     path to the browser executable.
+  --extension                  Connect to a running browser instance
+                               (Edge/Chrome only). Requires the "Playwright MCP
+                               Bridge" browser extension to be installed.
   --headless                   run browser in headless mode, headed by default
   --host <host>                host to bind server to. Default is localhost. Use
                                0.0.0.0 to bind to all interfaces.
@@ -191,7 +232,7 @@ Playwright MCP server supports following arguments. They can be provided in the
 
 ### User profile
 
-You can run Playwright MCP with persistent profile like a regular browser (default), or in the isolated contexts for the testing sessions.
+You can run Playwright MCP with persistent profile like a regular browser (default), in isolated contexts for testing sessions, or connect to your existing browser using the browser extension.
 
 **Persistent profile**
 
@@ -231,6 +272,10 @@ state [here](https://playwright.dev/docs/auth).
 }
 ```
 
+**Browser Extension**
+
+The Playwright MCP Chrome Extension allows you to connect to existing browser tabs and leverage your logged-in sessions and browser state. See [extension/README.md](extension/README.md) for installation and setup instructions.
+
 ### Configuration file
 
 The Playwright MCP server can be configured using a JSON configuration file. You can specify the configuration file
@@ -449,6 +494,15 @@ http.createServer(async (req, res) => {
 
 <!-- NOTE: This has been generated via update-readme.js -->
 
+- **browser_fill_form**
+  - Title: Fill form
+  - Description: Fill multiple form fields
+  - Parameters:
+    - `fields` (array): Fields to fill in
+  - Read-only: **false**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
 - **browser_handle_dialog**
   - Title: Handle a dialog
   - Description: Handle a dialog
@@ -486,14 +540,6 @@ http.createServer(async (req, res) => {
 
 <!-- NOTE: This has been generated via update-readme.js -->
 
-- **browser_navigate_forward**
-  - Title: Go forward
-  - Description: Go forward to the next page
-  - Parameters: None
-  - Read-only: **true**
-
-<!-- NOTE: This has been generated via update-readme.js -->
-
 - **browser_network_requests**
   - Title: List network requests
   - Description: Returns all network requests since loading the page
@@ -582,39 +628,14 @@ http.createServer(async (req, res) => {
 
 <!-- NOTE: This has been generated via update-readme.js -->
 
-- **browser_tab_close**
-  - Title: Close a tab
-  - Description: Close a tab
+- **browser_tabs**
+  - Title: Manage tabs
+  - Description: List, create, close, or select a browser tab.
   - Parameters:
-    - `index` (number, optional): The index of the tab to close. Closes current tab if not provided.
+    - `action` (string): Operation to perform
+    - `index` (number, optional): Tab index, used for close/select. If omitted for close, current tab is closed.
   - Read-only: **false**
 
-<!-- NOTE: This has been generated via update-readme.js -->
-
-- **browser_tab_list**
-  - Title: List tabs
-  - Description: List browser tabs
-  - Parameters: None
-  - Read-only: **true**
-
-<!-- NOTE: This has been generated via update-readme.js -->
-
-- **browser_tab_new**
-  - Title: Open a new tab
-  - Description: Open a new tab
-  - Parameters:
-    - `url` (string, optional): The URL to navigate to in the new tab. If not provided, the new tab will be blank.
-  - Read-only: **true**
-
-<!-- NOTE: This has been generated via update-readme.js -->
-
-- **browser_tab_select**
-  - Title: Select a tab
-  - Description: Select a tab by index
-  - Parameters:
-    - `index` (number): The index of the tab to select
-  - Read-only: **true**
-
 </details>
 
 <details>

package/config.d.ts

@@ -16,7 +16,7 @@
 
 import type * as playwright from 'playwright';
 
-export type ToolCapability = 'core' | 'core-tabs' | 'core-install' | 'vision' | 'pdf';
+export type ToolCapability = 'core' | 'core-tabs' | 'core-install' | 'vision' | 'pdf' | 'verify';
 
 export type Config = {
   /**

package/lib/browserContextFactory.js

@@ -19,8 +19,10 @@ import path from 'path';
 import * as playwright from 'playwright';
 // @ts-ignore
 import { registryDirectory } from 'playwright-core/lib/server/registry/index';
-import { logUnhandledError, testDebug } from './log.js';
-import { createHash } from './utils.js';
+// @ts-ignore
+import { startTraceViewerServer } from 'playwright-core/lib/server';
+import { logUnhandledError, testDebug } from './utils/log.js';
+import { createHash } from './utils/guid.js';
 import { outputFile } from './config.js';
 export function contextFactory(config) {
     if (config.browser.remoteEndpoint)
@@ -32,21 +34,18 @@ export function contextFactory(config) {
     return new PersistentContextFactory(config);
 }
 class BaseContextFactory {
-    name;
-    description;
     config;
+    _logName;
     _browserPromise;
-    _tracesDir;
-    constructor(name, description, config) {
-        this.name = name;
-        this.description = description;
+    constructor(name, config) {
+        this._logName = name;
         this.config = config;
     }
-    async _obtainBrowser() {
+    async _obtainBrowser(clientInfo) {
         if (this._browserPromise)
             return this._browserPromise;
-        testDebug(`obtain browser (${this.name})`);
-        this._browserPromise = this._doObtainBrowser();
+        testDebug(`obtain browser (${this._logName})`);
+        this._browserPromise = this._doObtainBrowser(clientInfo);
         void this._browserPromise.then(browser => {
             browser.on('disconnected', () => {
                 this._browserPromise = undefined;
@@ -56,14 +55,12 @@ class BaseContextFactory {
         });
         return this._browserPromise;
     }
-    async _doObtainBrowser() {
+    async _doObtainBrowser(clientInfo) {
         throw new Error('Not implemented');
     }
     async createContext(clientInfo) {
-        if (this.config.saveTrace)
-            this._tracesDir = await outputFile(this.config, clientInfo.rootPath, `traces-${Date.now()}`);
-        testDebug(`create browser context (${this.name})`);
-        const browser = await this._obtainBrowser();
+        testDebug(`create browser context (${this._logName})`);
+        const browser = await this._obtainBrowser(clientInfo);
         const browserContext = await this._doCreateContext(browser);
         return { browserContext, close: () => this._closeBrowserContext(browserContext, browser) };
     }
@@ -71,25 +68,25 @@ class BaseContextFactory {
         throw new Error('Not implemented');
     }
     async _closeBrowserContext(browserContext, browser) {
-        testDebug(`close browser context (${this.name})`);
+        testDebug(`close browser context (${this._logName})`);
         if (browser.contexts().length === 1)
             this._browserPromise = undefined;
         await browserContext.close().catch(logUnhandledError);
         if (browser.contexts().length === 0) {
-            testDebug(`close browser (${this.name})`);
+            testDebug(`close browser (${this._logName})`);
             await browser.close().catch(logUnhandledError);
         }
     }
 }
 class IsolatedContextFactory extends BaseContextFactory {
     constructor(config) {
-        super('isolated', 'Create a new isolated browser context', config);
+        super('isolated', config);
     }
-    async _doObtainBrowser() {
+    async _doObtainBrowser(clientInfo) {
         await injectCdpPort(this.config.browser);
         const browserType = playwright[this.config.browser.browserName];
         return browserType.launch({
-            tracesDir: this._tracesDir,
+            tracesDir: await startTraceServer(this.config, clientInfo.rootPath),
             ...this.config.browser.launchOptions,
             handleSIGINT: false,
             handleSIGTERM: false,
@@ -105,7 +102,7 @@ class IsolatedContextFactory extends BaseContextFactory {
 }
 class CdpContextFactory extends BaseContextFactory {
     constructor(config) {
-        super('cdp', 'Connect to a browser over CDP', config);
+        super('cdp', config);
     }
     async _doObtainBrowser() {
         return playwright.chromium.connectOverCDP(this.config.browser.cdpEndpoint);
@@ -116,7 +113,7 @@ class CdpContextFactory extends BaseContextFactory {
 }
 class RemoteContextFactory extends BaseContextFactory {
     constructor(config) {
-        super('remote', 'Connect to a browser using a remote endpoint', config);
+        super('remote', config);
     }
     async _doObtainBrowser() {
         const url = new URL(this.config.browser.remoteEndpoint);
@@ -141,9 +138,7 @@ class PersistentContextFactory {
         await injectCdpPort(this.config.browser);
         testDebug('create browser context (persistent)');
         const userDataDir = this.config.browser.userDataDir ?? await this._createUserDataDir(clientInfo.rootPath);
-        let tracesDir;
-        if (this.config.saveTrace)
-            tracesDir = await outputFile(this.config, clientInfo.rootPath, `traces-${Date.now()}`);
+        const tracesDir = await startTraceServer(this.config, clientInfo.rootPath);
         this._userDataDirs.add(userDataDir);
         testDebug('lock user data dir', userDataDir);
         const browserType = playwright[this.config.browser.browserName];
@@ -203,3 +198,14 @@ async function findFreePort() {
         server.on('error', reject);
     });
 }
+async function startTraceServer(config, rootPath) {
+    if (!config.saveTrace)
+        return undefined;
+    const tracesDir = await outputFile(config, rootPath, `traces-${Date.now()}`);
+    const server = await startTraceViewerServer();
+    const urlPrefix = server.urlPrefix('human-readable');
+    const url = urlPrefix + '/trace/index.html?trace=' + tracesDir + '/trace.json';
+    // eslint-disable-next-line no-console
+    console.error('\nTrace viewer listening on ' + url);
+    return tracesDir;
+}

package/lib/browserServerBackend.js

@@ -14,35 +14,26 @@
  * limitations under the License.
  */
 import { fileURLToPath } from 'url';
-import { z } from 'zod';
 import { Context } from './context.js';
-import { logUnhandledError } from './log.js';
+import { logUnhandledError } from './utils/log.js';
 import { Response } from './response.js';
 import { SessionLog } from './sessionLog.js';
 import { filteredTools } from './tools.js';
-import { packageJSON } from './package.js';
-import { defineTool } from './tools/tool.js';
+import { toMcpTool } from './mcp/tool.js';
 export class BrowserServerBackend {
-    name = 'Playwright';
-    version = packageJSON.version;
     _tools;
     _context;
     _sessionLog;
     _config;
     _browserContextFactory;
-    constructor(config, factories) {
+    constructor(config, factory) {
         this._config = config;
-        this._browserContextFactory = factories[0];
+        this._browserContextFactory = factory;
         this._tools = filteredTools(config);
-        if (factories.length > 1)
-            this._tools.push(this._defineContextSwitchTool(factories));
     }
-    async initialize(server) {
-        const capabilities = server.getClientCapabilities();
+    async initialize(server, clientVersion, roots) {
         let rootPath;
-        if (capabilities.roots && (server.getClientVersion()?.name === 'Visual Studio Code' ||
-            server.getClientVersion()?.name === 'Visual Studio Code - Insiders')) {
-            const { roots } = await server.listRoots();
+        if (roots.length > 0) {
             const firstRootUri = roots[0]?.uri;
             const url = firstRootUri ? new URL(firstRootUri) : undefined;
             rootPath = url ? fileURLToPath(url) : undefined;
@@ -53,17 +44,20 @@ export class BrowserServerBackend {
             config: this._config,
             browserContextFactory: this._browserContextFactory,
             sessionLog: this._sessionLog,
-            clientInfo: { ...server.getClientVersion(), rootPath },
+            clientInfo: { ...clientVersion, rootPath },
         });
     }
-    tools() {
-        return this._tools.map(tool => tool.schema);
+    async listTools() {
+        return this._tools.map(tool => toMcpTool(tool.schema));
     }
-    async callTool(schema, parsedArguments) {
+    async callTool(name, rawArguments) {
+        const tool = this._tools.find(tool => tool.schema.name === name);
+        if (!tool)
+            throw new Error(`Tool "${name}" not found`);
+        const parsedArguments = tool.schema.inputSchema.parse(rawArguments || {});
         const context = this._context;
-        const response = new Response(context, schema.name, parsedArguments);
-        const tool = this._tools.find(tool => tool.schema.name === schema.name);
-        context.setRunningTool(true);
+        const response = new Response(context, name, parsedArguments);
+        context.setRunningTool(name);
         try {
             await tool.handle(context, parsedArguments, response);
             await response.finish();
@@ -73,49 +67,11 @@ export class BrowserServerBackend {
             response.addError(String(error));
         }
         finally {
-            context.setRunningTool(false);
+            context.setRunningTool(undefined);
         }
         return response.serialize();
     }
     serverClosed() {
-        void this._context.dispose().catch(logUnhandledError);
-    }
-    _defineContextSwitchTool(factories) {
-        const self = this;
-        return defineTool({
-            capability: 'core',
-            schema: {
-                name: 'browser_connect',
-                title: 'Connect to a browser context',
-                description: [
-                    'Connect to a browser using one of the available methods:',
-                    ...factories.map(factory => `- "${factory.name}": ${factory.description}`),
-                ].join('\n'),
-                inputSchema: z.object({
-                    method: z.enum(factories.map(factory => factory.name)).default(factories[0].name).describe('The method to use to connect to the browser'),
-                }),
-                type: 'readOnly',
-            },
-            async handle(context, params, response) {
-                const factory = factories.find(factory => factory.name === params.method);
-                if (!factory) {
-                    response.addError('Unknown connection method: ' + params.method);
-                    return;
-                }
-                await self._setContextFactory(factory);
-                response.addResult('Successfully changed connection method.');
-            }
-        });
-    }
-    async _setContextFactory(newFactory) {
-        if (this._context) {
-            const options = {
-                ...this._context.options,
-                browserContextFactory: newFactory,
-            };
-            await this._context.dispose();
-            this._context = new Context(options);
-        }
-        this._browserContextFactory = newFactory;
+        void this._context?.dispose().catch(logUnhandledError);
     }
 }

package/lib/config.js

@@ -17,7 +17,7 @@ import fs from 'fs';
 import os from 'os';
 import path from 'path';
 import { devices } from 'playwright';
-import { sanitizeForFilePath } from './utils.js';
+import { sanitizeForFilePath } from './utils/fileUtils.js';
 const defaultConfig = {
     browser: {
         browserName: 'chromium',

package/lib/context.js

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 import debug from 'debug';
-import { logUnhandledError } from './log.js';
+import { logUnhandledError } from './utils/log.js';
 import { Tab } from './tab.js';
 import { outputFile } from './config.js';
 const testDebug = debug('pw:mcp:test');
@@ -30,7 +30,7 @@ export class Context {
     _clientInfo;
     static _allContexts = new Set();
     _closeBrowserContextPromise;
-    _isRunningTool = false;
+    _runningToolName;
     _abortController = new AbortController();
     constructor(options) {
         this.tools = options.tools;
@@ -110,10 +110,10 @@ export class Context {
         this._closeBrowserContextPromise = undefined;
     }
     isRunningTool() {
-        return this._isRunningTool;
+        return this._runningToolName !== undefined;
     }
-    setRunningTool(isRunningTool) {
-        this._isRunningTool = isRunningTool;
+    setRunningTool(name) {
+        this._runningToolName = name;
     }
     async _closeBrowserContextImpl() {
         if (!this._browserContextPromise)
@@ -156,7 +156,7 @@ export class Context {
         if (this._closeBrowserContextPromise)
             throw new Error('Another browser context is being closed.');
         // TODO: move to the browser context factory to make it based on isolation mode.
-        const result = await this._browserContextFactory.createContext(this._clientInfo, this._abortController.signal);
+        const result = await this._browserContextFactory.createContext(this._clientInfo, this._abortController.signal, this._runningToolName);
         const { browserContext } = result;
         await this._setupRequestInterception(browserContext);
         if (this.sessionLog)

package/lib/extension/cdpRelay.js

@@ -23,9 +23,10 @@
 import { spawn } from 'child_process';
 import debug from 'debug';
 import { WebSocket, WebSocketServer } from 'ws';
-import { httpAddressToString } from '../httpServer.js';
-import { logUnhandledError } from '../log.js';
-import { ManualPromise } from '../manualPromise.js';
+import { httpAddressToString } from '../mcp/http.js';
+import { logUnhandledError } from '../utils/log.js';
+import { ManualPromise } from '../mcp/manualPromise.js';
+import * as protocol from './protocol.js';
 // @ts-ignore
 const { registry } = await import('playwright-core/lib/server/registry/index');
 const debugLogger = debug('pw:mcp:relay');
@@ -33,6 +34,7 @@ export class CDPRelayServer {
     _wsHost;
     _browserChannel;
     _userDataDir;
+    _executablePath;
     _cdpPath;
     _extensionPath;
     _wss;
@@ -41,10 +43,11 @@ export class CDPRelayServer {
     _connectedTabInfo;
     _nextSessionId = 1;
     _extensionConnectionPromise;
-    constructor(server, browserChannel, userDataDir) {
+    constructor(server, browserChannel, userDataDir, executablePath) {
         this._wsHost = httpAddressToString(server.address()).replace(/^http/, 'ws');
         this._browserChannel = browserChannel;
         this._userDataDir = userDataDir;
+        this._executablePath = executablePath;
         const uuid = crypto.randomUUID();
         this._cdpPath = `/cdp/${uuid}`;
         this._extensionPath = `/extension/${uuid}`;
@@ -58,31 +61,44 @@ export class CDPRelayServer {
     extensionEndpoint() {
         return `${this._wsHost}${this._extensionPath}`;
     }
-    async ensureExtensionConnectionForMCPContext(clientInfo, abortSignal) {
+    async ensureExtensionConnectionForMCPContext(clientInfo, abortSignal, toolName) {
         debugLogger('Ensuring extension connection for MCP context');
         if (this._extensionConnection)
             return;
-        this._connectBrowser(clientInfo);
+        this._connectBrowser(clientInfo, toolName);
         debugLogger('Waiting for incoming extension connection');
         await Promise.race([
             this._extensionConnectionPromise,
+            new Promise((_, reject) => setTimeout(() => {
+                reject(new Error(`Extension connection timeout. Make sure the "Playwright MCP Bridge" extension is installed. See https://github.com/microsoft/playwright-mcp/blob/main/extension/README.md for installation instructions.`));
+            }, process.env.PWMCP_TEST_CONNECTION_TIMEOUT ? parseInt(process.env.PWMCP_TEST_CONNECTION_TIMEOUT, 10) : 5_000)),
             new Promise((_, reject) => abortSignal.addEventListener('abort', reject))
         ]);
         debugLogger('Extension connection established');
     }
-    _connectBrowser(clientInfo) {
+    _connectBrowser(clientInfo, toolName) {
         const mcpRelayEndpoint = `${this._wsHost}${this._extensionPath}`;
         // Need to specify "key" in the manifest.json to make the id stable when loading from file.
         const url = new URL('chrome-extension://jakfalbnbhgkpmoaakfflhflbfpkailf/connect.html');
         url.searchParams.set('mcpRelayUrl', mcpRelayEndpoint);
-        url.searchParams.set('client', JSON.stringify(clientInfo));
+        const client = {
+            name: clientInfo.name,
+            version: clientInfo.version,
+        };
+        url.searchParams.set('client', JSON.stringify(client));
+        url.searchParams.set('protocolVersion', process.env.PWMCP_TEST_PROTOCOL_VERSION ?? protocol.VERSION.toString());
+        if (toolName)
+            url.searchParams.set('newTab', String(toolName === 'browser_navigate'));
         const href = url.toString();
-        const executableInfo = registry.findExecutable(this._browserChannel);
-        if (!executableInfo)
-            throw new Error(`Unsupported channel: "${this._browserChannel}"`);
-        const executablePath = executableInfo.executablePath();
-        if (!executablePath)
-            throw new Error(`"${this._browserChannel}" executable not found. Make sure it is installed at a standard location.`);
+        let executablePath = this._executablePath;
+        if (!executablePath) {
+            const executableInfo = registry.findExecutable(this._browserChannel);
+            if (!executableInfo)
+                throw new Error(`Unsupported channel: "${this._browserChannel}"`);
+            executablePath = executableInfo.executablePath();
+            if (!executablePath)
+                throw new Error(`"${this._browserChannel}" executable not found. Make sure it is installed at a standard location.`);
+        }
         const args = [];
         if (this._userDataDir)
             args.push(`--user-data-dir=${this._userDataDir}`);
@@ -186,10 +202,6 @@ export class CDPRelayServer {
                     params: params.params
                 });
                 break;
-            case 'detachedFromTab':
-                debugLogger('← Debugger detached from tab:', params);
-                this._connectedTabInfo = undefined;
-                break;
         }
     }
     async _handlePlaywrightMessage(message) {
@@ -225,7 +237,7 @@ export class CDPRelayServer {
                 if (sessionId)
                     break;
                 // Simulate auto-attach behavior with real target info
-                const { targetInfo } = await this._extensionConnection.send('attachToTab');
+                const { targetInfo } = await this._extensionConnection.send('attachToTab', {});
                 this._connectedTabInfo = {
                     targetInfo,
                     sessionId: `pw-tab-${this._nextSessionId++}`,
@@ -275,11 +287,11 @@ class ExtensionConnection {
         this._ws.on('close', this._onClose.bind(this));
         this._ws.on('error', this._onError.bind(this));
     }
-    async send(method, params, sessionId) {
+    async send(method, params) {
         if (this._ws.readyState !== WebSocket.OPEN)
             throw new Error(`Unexpected WebSocket state: ${this._ws.readyState}`);
         const id = ++this._lastId;
-        this._ws.send(JSON.stringify({ id, method, params, sessionId }));
+        this._ws.send(JSON.stringify({ id, method, params }));
         const error = new Error(`Protocol error: ${method}`);
         return new Promise((resolve, reject) => {
             this._callbacks.set(id, { resolve, reject, error });

package/lib/extension/extensionContextFactory.js

@@ -15,20 +15,20 @@
  */
 import debug from 'debug';
 import * as playwright from 'playwright';
-import { startHttpServer } from '../httpServer.js';
+import { startHttpServer } from '../mcp/http.js';
 import { CDPRelayServer } from './cdpRelay.js';
 const debugLogger = debug('pw:mcp:relay');
 export class ExtensionContextFactory {
-    name = 'extension';
-    description = 'Connect to a browser using the Playwright MCP extension';
     _browserChannel;
     _userDataDir;
-    constructor(browserChannel, userDataDir) {
+    _executablePath;
+    constructor(browserChannel, userDataDir, executablePath) {
         this._browserChannel = browserChannel;
         this._userDataDir = userDataDir;
+        this._executablePath = executablePath;
     }
-    async createContext(clientInfo, abortSignal) {
-        const browser = await this._obtainBrowser(clientInfo, abortSignal);
+    async createContext(clientInfo, abortSignal, toolName) {
+        const browser = await this._obtainBrowser(clientInfo, abortSignal, toolName);
         return {
             browserContext: browser.contexts()[0],
             close: async () => {
@@ -37,9 +37,9 @@ export class ExtensionContextFactory {
             }
         };
     }
-    async _obtainBrowser(clientInfo, abortSignal) {
+    async _obtainBrowser(clientInfo, abortSignal, toolName) {
         const relay = await this._startRelay(abortSignal);
-        await relay.ensureExtensionConnectionForMCPContext(clientInfo, abortSignal);
+        await relay.ensureExtensionConnectionForMCPContext(clientInfo, abortSignal, toolName);
         return await playwright.chromium.connectOverCDP(relay.cdpEndpoint());
     }
     async _startRelay(abortSignal) {
@@ -48,7 +48,7 @@ export class ExtensionContextFactory {
             httpServer.close();
             throw new Error(abortSignal.reason);
         }
-        const cdpRelayServer = new CDPRelayServer(httpServer, this._browserChannel, this._userDataDir);
+        const cdpRelayServer = new CDPRelayServer(httpServer, this._browserChannel, this._userDataDir, this._executablePath);
         abortSignal.addEventListener('abort', () => cdpRelayServer.stop());
         debugLogger(`CDP relay server started, extension endpoint: ${cdpRelayServer.extensionEndpoint()}.`);
         return cdpRelayServer;

package/lib/extension/protocol.js

@@ -0,0 +1,18 @@
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+// Whenever the commands/events change, the version must be updated. The latest
+// extension version should be compatible with the old MCP clients.
+export const VERSION = 1;