Attach to Existing Browser

View as Markdown

By default, new_session launches a fresh Chromium browser. If you want your coding agent to interact with a browser you already have open — with existing login state, cookies, tabs, and extensions — attach to it instead.

Simpler alternative

For most cases, a persistent Chrome profile is simpler and doesn't require any setup. Use the approaches below only when you need to interact with a browser that's already running.

Option 1: Chrome Extension Relay (recommended)

The Shiplight Chrome extension acts as a relay between your agent and your real Chrome browser. Once configured, your agent can auto-discover tabs — no URL or per-session setup needed.

Attach to my browser and check if the payment form
on the current page has any console errors.

Setup

1. Install the Chrome extension

The extension is bundled with the MCP server. To get the path:

npx @shiplightai/mcp --chrome-extension-path

Then load it in Chrome:

• Open chrome://extensions
• Enable Developer mode (toggle in top right)
• Click Load unpacked and select the path from above

2. Enable the relay server

Add SHIPLIGHT_RELAY_PORT to your project's .env:

SHIPLIGHT_RELAY_PORT=15170

Reconnect the MCP server (e.g. /mcp in Claude Code) — the relay server starts automatically on the specified port.

3. Configure the extension

• Right-click the Shiplight extension icon → Options
• Set Relay Server Port to 15170 (must match your .env)
• Click Save Settings

4. Attach a tab

Navigate to the page you want to control, then click the Shiplight extension icon. The badge shows ON (orange) when the tab is attached and connected.

Badge indicators:

• ON (orange) — tab attached and connected
• … (yellow) — reconnecting
• ! (red) — error, check extension options

Option 2: Direct CDP Connection

You can also connect directly via the Chrome DevTools Protocol without the extension. Start Chrome with --remote-debugging-port=9222, then:

Attach to my browser at ws://localhost:9222/devtools/browser/...

This is more manual than the extension relay (you have to pass an explicit WebSocket URL) but it doesn't require installing anything.