---
title: Attach to your browser
description: Use the Shiplight MCP relay to connect your coding agent to an existing Chrome tab for interactive verification and diagnosis.
---

# Attach to your browser

<div class="view-markdown-wrapper">
<ViewMarkdown />
</div>

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.

::: tip 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](/local/agent-workflow/authentication). If you only need to preserve login state during local verification, use a [persistent Chrome profile](/guides/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:

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

In 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=15170
```

**3. 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.
```