fix: tolerate unresponsive tabs when connecting to existing browser

When connecting to a running browser via --browserUrl, browser.pages()
hangs indefinitely if any tab is unresponsive (discarded by memory
management, dead localhost, etc). This blocks all tool calls since page
enumeration runs on every request.

Two changes:

1. Add protocolTimeout (15s) to puppeteer.connect() so CDP commands
   fail with an error instead of hanging forever.

2. Wrap browser.pages() in #getAllPages() with a 10s timeout. If it
   fails, fall back to per-target enumeration: iterate browser.targets(),
   call target.page() on each with a 5s timeout, and skip tabs that
   don't respond. This way one unresponsive tab doesn't block the
   entire server.

Tested with Chrome/Brave 145, 28 open tabs (5 discarded). Without this
fix the server hangs forever on the first tool call. With the fix it
returns 23 responsive pages in ~12s and logs the 5 it skipped.

Related: puppeteer/puppeteer#5633, puppeteer/puppeteer#14708, #870, #978

Author: jaidhyani

README.md

@@ -560,6 +560,11 @@ The Chrome DevTools MCP server supports the following configuration option:
   If enabled, ignores errors relative to self-signed and expired certificates. Use with caution.
   - **Type:** boolean
 
+- **`--skipUnresponsiveTabs`/ `--skip-unresponsive-tabs`**
+  When connecting to an existing browser, skip tabs that don't respond to CDP commands (e.g. discarded or sleeping tabs) instead of hanging indefinitely. Recommended when using `--browserUrl` or `--wsEndpoint` with a browser that has many open tabs.
+  - **Type:** boolean
+  - **Default:** false
+
 - **`--experimentalVision`/ `--experimental-vision`**
   Whether to enable coordinate-based tools such as click_at(x,y). Usually requires a computer-use model able to produce accurate coordinates by looking at screenshots.
   - **Type:** boolean
@@ -725,6 +730,8 @@ trace.
 
 You can connect to a running Chrome instance by using the `--browser-url` option. This is useful if you are running the MCP server in a sandboxed environment that does not allow starting a new Chrome instance.
 
+If you have many tabs open, some may be discarded by the browser to save memory. These tabs don't respond to CDP commands, which can cause the MCP server to hang on startup. Use `--skip-unresponsive-tabs` to automatically detect and skip these tabs.
+
 Here is a step-by-step guide on how to connect to a running Chrome instance:
 
 **Step 1: Configure the MCP client**

src/McpContext.ts

@@ -56,6 +56,8 @@ interface McpContextOptions {
   experimentalIncludeAllPages?: boolean;
   // Whether CrUX data should be fetched.
   performanceCrux: boolean;
+  // Whether to skip unresponsive tabs when enumerating pages.
+  skipUnresponsiveTabs?: boolean;
 }
 
 const DEFAULT_TIMEOUT = 5_000;
@@ -562,9 +564,53 @@ export class McpContext implements Context {
     isolatedContextNames: Map<Page, string>;
   }> {
     const defaultCtx = this.browser.defaultBrowserContext();
-    const allPages = await this.browser.pages(
-      this.#options.experimentalIncludeAllPages,
-    );
+
+    let allPages: Page[];
+    if (this.#options.skipUnresponsiveTabs) {
+      // Tolerant page enumeration: browser.pages() hangs indefinitely when
+      // any tab is unresponsive (e.g. discarded/sleeping tabs). Fall back to
+      // per-target enumeration so that one bad tab doesn't block the server.
+      try {
+        allPages = await Promise.race([
+          this.browser.pages(this.#options.experimentalIncludeAllPages),
+          new Promise<never>((_, reject) =>
+            setTimeout(
+              () => reject(new Error('browser.pages() timed out')),
+              10_000,
+            ),
+          ),
+        ]);
+      } catch {
+        this.logger(
+          'browser.pages() timed out — falling back to per-target enumeration',
+        );
+        const pageTargets = this.browser
+          .targets()
+          .filter(t => t.type() === 'page');
+        allPages = [];
+        await Promise.all(
+          pageTargets.map(async target => {
+            try {
+              const page = await Promise.race([
+                target.page(),
+                new Promise<never>((_, reject) =>
+                  setTimeout(() => reject(new Error('timeout')), 5_000),
+                ),
+              ]);
+              if (page) {
+                allPages.push(page);
+              }
+            } catch {
+              this.logger(`Skipping unresponsive tab: ${target.url()}`);
+            }
+          }),
+        );
+      }
+    } else {
+      allPages = await this.browser.pages(
+        this.#options.experimentalIncludeAllPages,
+      );
+    }
 
     const allTargets = this.browser.targets();
     const extensionTargets = allTargets.filter(target => {

src/bin/chrome-devtools-mcp-cli-options.ts

@@ -147,6 +147,11 @@ export const cliOptions = {
     type: 'boolean',
     description: `If enabled, ignores errors relative to self-signed and expired certificates. Use with caution.`,
   },
+  skipUnresponsiveTabs: {
+    type: 'boolean',
+    description: `When connecting to an existing browser, skip tabs that don't respond to CDP commands (e.g. discarded or sleeping tabs) instead of hanging. Recommended when using --browserUrl with many open tabs.`,
+    default: false,
+  },
   experimentalPageIdRouting: {
     type: 'boolean',
     describe:

src/browser.ts

@@ -51,6 +51,7 @@ export async function ensureBrowserConnected(options: {
   channel?: Channel;
   userDataDir?: string;
   enableExtensions?: boolean;
+  skipUnresponsiveTabs?: boolean;
 }) {
   const {channel, enableExtensions} = options;
   if (browser?.connected) {
@@ -61,6 +62,7 @@ export async function ensureBrowserConnected(options: {
     targetFilter: makeTargetFilter(enableExtensions),
     defaultViewport: null,
     handleDevToolsAsPage: true,
+    ...(options.skipUnresponsiveTabs ? {protocolTimeout: 15_000} : {}),
   };
 
   let autoConnect = false;

src/index.ts

@@ -86,6 +86,7 @@ export async function createMcpServer(
               : undefined,
             userDataDir: serverArgs.userDataDir,
             devtools,
+            skipUnresponsiveTabs: serverArgs.skipUnresponsiveTabs,
           })
         : await ensureBrowserLaunched({
             headless: serverArgs.headless,
@@ -108,6 +109,7 @@ export async function createMcpServer(
         experimentalDevToolsDebugging: devtools,
         experimentalIncludeAllPages: serverArgs.experimentalIncludeAllPages,
         performanceCrux: serverArgs.performanceCrux,
+        skipUnresponsiveTabs: serverArgs.skipUnresponsiveTabs,
       });
     }
     return context;