Troubleshooting

Start with the symptom below. Most connection problems resolve by restarting the MCP server from your AI client, then reconnecting the extension.

The extension cannot connect

Confirm mcpX appears as running in your AI client.
Open the extension popup and select Connect browser again.
Reload the extension from chrome://extensions.
Restart the AI client so it launches a fresh server process.

The server prefers port 3000 and automatically searches through 3010. If every port is occupied, stop the stale process or application using the range.

macOS or Linux:

lsof -nP -iTCP:3000-3010 -sTCP:LISTEN

Windows:

netstat -ano | findstr "3000 3001 3002 3003 3004 3005 3006 3007 3008 3009 3010"

Do not run two mcpX servers for the same browser. If you set MCPX_PORT, the port is strict and startup fails instead of selecting another one.

A tab cannot be found

Tab IDs can change when tabs close or browser windows restart. Call tabs-list again and retry with the current ID.

A page is restricted

mcpX operates on ordinary HTTP and HTTPS pages. Chrome settings, extension pages, the Chrome Web Store, file:, data:, and other protected schemes may reject automation by design.

Take a new snapshot after navigation or a large document update. References from the previous document generation intentionally return ELEMENT_NOT_FOUND rather than targeting a potentially different element.

A locator is ambiguous

The locator matched more than one element. Add nth, use a stable test ID, or combine a role with an accessible name.

A screenshot or console call says debugger unavailable

Close DevTools for the target tab and stop any other extension that attached a debugger, then retry. Chrome permits only one debugger owner for the tab.

Console history is empty

Call console-start before reproducing the issue. Chrome does not provide past console events to the extension. When finished, call console-stop to release the debugger attachment.

Still stuck

Open a GitHub issue with:

Your operating system, Chrome version, Node.js version, and mcpX version
The MCP client you use
The tool name and typed error code
Minimal reproduction steps

Remove pairing tokens, page contents, screenshots with personal data, cookies, and credentials before posting.