docs: add VM-to-host remote debugging workaround

Author: rust17

README.md

@@ -48,7 +48,7 @@ Add the following config to your MCP client:
 }
 ```
 
-> [!NOTE]  
+> [!NOTE]
 > Using `chrome-devtools-mcp@latest` ensures that your MCP client will always use the latest version of the Chrome DevTools MCP server.
 
 ### MCP Client configuration
@@ -134,7 +134,7 @@ Configure the following fields and press `CTRL+S` to save the configuration:
   <summary>Copilot / VS Code</summary>
   Follow the MCP install <a href="https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_add-an-mcp-server">guide</a>,
   with the standard config from above. You can also install the Chrome DevTools MCP server using the VS Code CLI:
-  
+
   ```bash
   code --add-mcp '{"name":"chrome-devtools","command":"npx","args":["chrome-devtools-mcp@latest"]}'
   ```
@@ -207,9 +207,9 @@ Alternatively, follow the <a href="https://docs.qoder.com/user-guide/chat/model-
 
 <details>
   <summary>Visual Studio</summary>
-  
+
   **Click the button to install:**
-  
+
   [<img src="https://img.shields.io/badge/Visual_Studio-Install-C16FDE?logo=visualstudio&logoColor=white" alt="Install in Visual Studio">](https://vs-open.link/mcp-install?%7B%22name%22%3A%22chrome-devtools%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22chrome-devtools-mcp%40latest%22%5D%7D)
 </details>
 
@@ -230,7 +230,7 @@ Check the performance of https://developers.chrome.com
 
 Your MCP client should open the browser and record a performance trace.
 
-> [!NOTE]  
+> [!NOTE]
 > The MCP server will start the browser automatically once the MCP client uses a tool that requires a running browser instance. Connecting to the Chrome DevTools MCP server on its own will not automatically start the browser.
 
 ## Tools
@@ -386,7 +386,7 @@ Add the `--browser-url` option to your MCP client configuration. The value of th
 
 **Step 2: Start the Chrome browser**
 
-> [!WARNING]  
+> [!WARNING]
 > Enabling the remote debugging port opens up a debugging port on the running browser instance. Any application on your machine can connect to this port and control the browser. Make sure that you are not browsing any sensitive websites while the debugging port is open.
 
 Start the Chrome browser with the remote debugging port enabled. Make sure to close any running Chrome instances before starting a new one with the debugging port enabled. The port number you choose must be the same as the one you specified in the `--browser-url` option in your MCP client configuration.
@@ -423,6 +423,8 @@ Your MCP client should connect to the running Chrome instance and receive a perf
 
 For more details on remote debugging, see the [Chrome DevTools documentation](https://developer.chrome.com/docs/devtools/remote-debugging/).
 
+If you hit VM-to-host port forwarding issues, see the “Remote debugging between virtual machine (VM) and host fails” section in [`docs/troubleshooting.md`](./docs/troubleshooting.md#remote-debugging-between-virtual-machine-vm-and-host-fails).
+
 ## Known limitations
 
 ### Operating system sandboxes

docs/troubleshooting.md

@@ -27,3 +27,14 @@ npm cache clean --force
 This indicates that the browser could not be started. Make sure that no Chrome
 instances are running or close them. Make sure you have the latest stable Chrome
 installed and that [your system is able to run Chrome](https://support.google.com/chrome/a/answer/7100626?hl=en).
+
+### Remote debugging between virtual machine (VM) and host fails
+
+When connecting DevTools inside a VM to Chrome running on the host, any domain is rejected by Chrome because of host header validation. Tunneling the port over SSH bypasses this restriction. In the VM, run:
+
+```sh
+ssh -N -L 127.0.0.1:9222:127.0.0.1:9222 <user>@<host-ip>
+```
+
+Point the MCP connection inside the VM to `http://127.0.0.1:9222` and DevTools
+will reach the host browser without triggering the Host validation.