Attach to your browser
Use the Chrome relay for interactive verification and diagnosis, not for running automated tests. It is particularly useful when an issue occurs in production or depends on a user account and session that are already open in Chrome. Sign in with the appropriate account, attach the tab, and let your coding agent inspect and drive the page through the Shiplight MCP server.
The relay preserves the tab's current login state, data, and configured extensions. Your agent detects attached tabs automatically, so you do not need to provide a URL for each session.
Use managed browser sessions for automated tests
The relay is intended for one-time verification and diagnosis in an existing browser. Run automated YAML tests in isolated, repeatable browser sessions with test authentication. See Authentication. If you only need to preserve login state during local verification, use a persistent Chrome profile.
Setup — Chrome extension relay (recommended)
The Shiplight Chrome extension relays commands from the Shiplight MCP server to an attached Chrome tab. Complete the following setup once:
1. Install the Chrome extension. The extension is included with the MCP server. Run the following command to find its location:
npx @shiplightai/mcp --chrome-extension-pathIn Chrome, open chrome://extensions, enable Developer mode, select Load unpacked, and choose the directory returned by the command.
2. Enable the relay server. Add the following setting to your project's .env file, then reconnect the MCP server. For example, use /mcp in Claude Code.
SHIPLIGHT_RELAY_PORT=151703. Configure the extension. Right-click the Shiplight extension icon and select Options. Set Relay Server Port to 15170 so it matches your .env file, then save the setting.
4. Attach a tab. Open the page you want to verify and sign in with the appropriate account. Select the extension icon to attach the tab. The badge shows the connection status:
- ON (orange) — The tab is attached and connected.
- … (yellow) — The extension is reconnecting.
- ! (red) — A connection error occurred. Check the extension options.
Setup — direct CDP connection
You can also connect through the Chrome DevTools Protocol without installing the extension. Start Chrome with --remote-debugging-port=9222, then enter:
Attach to my browser at ws://localhost:9222/devtools/browser/...This method requires an explicit WebSocket URL for each connection, but does not require an extension.
Verify the attached tab
After you complete the setup and attach a tab, ask your coding agent to verify or diagnose the page. For example:
/shiplight verify — attach to my Chrome tab and diagnose why checkout
fails for this production account. Check the console and network logs,
but do not submit another order.