Channels
Chrome Connect Relay
By OpenClaw plugin for Artífice Connect — remote browser relay, CDP proxy, client pairing, and WhatsApp-to-browser routing
Install
npm install
```Configuration Example
{
"mcpServers": {
"artifice": {
"command": "node",
"args": [
"/absolute/path/to/chrome-connect-relay/bin/mcp-server.js"
],
"env": {
"ARTIFICE_PORT": "18792",
"ARTIFICE_HOST": "127.0.0.1"
}
}
}
}README
# Chrome Connect Relay
A WebSocket relay + MCP server that gives your AI agent CDP (Chrome DevTools Protocol) access to a connected browser. Ships as a Claude Code MCP server out of the box; a legacy plugin adapter is included for backward compatibility.
Once a browser is connected, your agent can navigate pages, click elements, fill forms, take screenshots, and run JavaScript — with you in control of which tabs are shared.
## How it works
```
Your AI agent
│
└─ Claude Code MCP: artifice_status, artifice_cdp
▼
chrome-connect-relay ← this repo
│ WebSocket on port 18792, token-authenticated
▼
chrome-connect-extension (browser)
│ Chrome DevTools Protocol
▼
Shared browser tabs
```
## MCP tools
| Tool | Description |
|------|-------------|
| `artifice_status` | Check connection status and list shared tabs with their `sessionId`s |
| `artifice_cdp` | Send allowed CDP commands to the connected browser, subject to the relay allowlist |
`artifice_cdp` returns the raw CDP response as JSON: `{ "result": { ... } }`. For example, a `Runtime.evaluate` returns `{ "result": { "result": { "type": "string", "value": "..." } } }`.
## Pairing tools (legacy plugin adapter)
The legacy plugin adapter (used by older Artifice-family agents) exposes two additional tools not surfaced via MCP:
| Tool | Description |
|------|-------------|
| `artifice_pair` | Generate a 6-digit pairing code (5-min TTL) |
| `artifice_redeem` | Redeem the code and get an `art_...` bearer token that expires after 8 hours |
Claude Code MCP does not expose pairing tools by design — tokens are minted out-of-band (via the legacy plugin adapter, a CLI script, or a trusted setup process) and configured directly into the browser extension.
---
## Setup — Claude Code
1. **Clone and install**
```bash
git clone https://github.com/artifice-ia/chrome-connect-relay.git
cd chrome-connect-relay
npm install
```
2. **Register as an MCP server**
Add to your `~/.claude.json` (Linux/Mac). On Windows, `%USERPROFILE%\.claude.json`.
```json
{
"mcpServers": {
"artifice": {
"command": "node",
"args": [
"/absolute/path/to/chrome-connect-relay/bin/mcp-server.js"
],
"env": {
"ARTIFICE_PORT": "18792",
"ARTIFICE_HOST": "127.0.0.1"
}
}
}
}
```
Replace `/absolute/path/to/chrome-connect-relay` with the actual path to the cloned directory. Run `pwd` inside the repo to get it. A `.mcp.json.example` file in this repo shows the full format — you can copy it to `~/.claude.json` or merge it into your existing one.
3. **Restart Claude Code** so the MCP server loads and the relay starts.
4. **Install the browser extension** — see [chrome-connect-extension](https://github.com/artifice-ia/chrome-connect-extension).
5. **Configure the extension with a pre-minted token.** Tokens are minted by the legacy plugin adapter's `artifice_pair`/`artifice_redeem` tools or another trusted setup script that calls the relay pairing APIs directly. Configure Claude Code's MCP server to point at the same `clients.json` used at minting — run from the same repo directory, or set `ARTIFICE_CLIENTS_FILE` explicitly.
6. **Verify in Claude Code**
Ask Claude Code:
> "Call `artifice_status`"
You should see `connected: true` once the extension is connected.
---
## Setup — legacy plugin adapter
The legacy plugin adapter registers via the older Artifice-family plugin API. Use this path if you need `artifice_pair` / `artifice_redeem` for the token-minting flow.
1. **Clone and install** (same as step 1 above)
2. **Configure the plugin** in your agent's plugin config:
```json
{
"plugins": {
"allow": [
"artifice"
],
"load": {
"paths": [
"/absolute/path/to/chrome-connect-relay"
]
},
"entries": {
"artifice": {
"enabled": true,
"config": {
"relayPort": 18792,
"relayHost": "127.0.0.1"
}
}
}
}
}
```
3. **Restart the agent** to load the plugin and start the relay. The plugin API does not hot-reload — a full restart is required on config changes.
4. **Install the browser extension** — see [chrome-connect-extension](https://github.com/artifice-ia/chrome-connect-extension).
5. **Pair your browser** — see [Pairing flow](#pairing-flow) below.
---
## Pairing flow
The extension authenticates with a bearer token. With the legacy plugin adapter, you generate the token via the plugin's pair/redeem tools and enter it into the extension options. Redeemed `art_...` tokens expire after 8 hours.
**Step 1 — Generate a pairing code**
Ask your agent:
> "Call `artifice_pair` with client name 'my-browser'"
The agent returns a 6-digit code valid for 5 minutes.
**Step 2 — Redeem it for a token**
Ask your agent:
> "Call `artifice_redeem` with code 123456"
(Use the actual code from step 1.) The agent returns an `art_...` bearer token that expires after 8 hours. Save this token — it is only shown once.
**Step 3 — Configure the extension**
Open the extension options page and set:
- **Relay URL:** `ws://127.0.0.1:18792`
- **Client Token:** paste the `art_...` token from step 2
Save. The extension connects automatically.
**Step 4 — Verify**
Ask your agent:
> "Call `artifice_status`"
You should see `connected: true` and the name you used in step 1.
**Step 5 — Share a tab**
Navigate to any page and click the extension icon to share that tab. Your agent can now target it with `artifice_cdp`.
> If the pairing code expires before you redeem it, call `artifice_pair` again to get a fresh one.
---
## Revoking access
Tokens are stored (hashed) in `clients.json` in the root of this repo. To revoke a client:
1. Stop the relay.
2. Open `clients.json` and remove the entry for that client.
3. Save the file.
4. Restart the relay so it reloads `clients.json`.
To issue a new token, run a fresh pair/redeem cycle. The new token expires 8 hours after redemption.
---
## Security
- **Relay access = full browser control on shared tabs.** A connected agent can navigate, click, type, evaluate JavaScript, capture screenshots, and read `localStorage`, `sessionStorage`, cookies, and any auth tokens visible to the page. Only share tabs you are comfortable giving the agent complete access to.
- **Tab access is revoked at the token level, not per-tab.** Removing a client entry from `clients.json` and restarting the relay disconnects that browser entirely and removes access to all its shared tabs. There is no per-tab revocation.
- **Default bind is loopback only (`127.0.0.1`).** Nothing is reachable from outside your machine without deliberate configuration. If you need remote access, use a reverse proxy with TLS termination — the token provides authentication; the proxy provides transport security. Do not expose port 18792 directly to the internet.
- **Tokens expire after 8 hours.** Redeemed `art_...` bearer tokens include an `expiresAt` timestamp and are rejected after that time.
- **Tokens are hashed at rest.** `clients.json` stores a hash of each token — the raw `art_...` value is never written to disk on the relay side. The raw token is shown once at redeem time; keep it out of version control.
- **Atomic `clients.json` writes.** Token records are written atomically to reduce corruption risk on crash or power loss.
- **Protocol version handshake** — relay and extension verify compatibility on connect. If versions don't match, the connection is rejected. If this happens, update both the relay and extension to the same version.
---
## CDP examples
`artifice_cdp` accepts only CDP methods allowed by the relay's CDP allowlist. If a method is not allowed, the relay rejects it with `CDP method not allowed`.
Navigate to a URL:
```json
{
"method": "Page.navigate",
"params": {
"url": "https://example.com"
}
}
```
Capture a screenshot:
```json
{
"method": "Page.captureScreenshot",
"params": {
"format": "png",
"fromSurface": true
}
}
```
Evaluate JavaScript:
```json
{
"method": "Runtime.evaluate",
"params": {
"expression": "document.title",
"returnByValue": true
}
}
```
Target a specific tab (get `sessionId` from `artifice_status`):
```json
{
"method": "Page.navigate",
"params": {
"url": "https://example.com"
},
"sessionId": "<id>"
}
```
---
## Troubleshooting
**MCP server won't start / tools not appearing in Claude Code**
- Check the path in `~/.claude.json` is absolute and correct — run `pwd` in the repo to verify.
- Run `node bin/mcp-server.js` manually to see startup errors.
- Restart Claude Code fully after editing `~/.claude.json`.
**Extension shows "disconnected" after entering token**
- Confirm the relay is running: `node bin/mcp-server.js` should print a startup message for Claude Code MCP, or the legacy plugin adapter should show the plugin loaded.
- Confirm the relay URL in the extension is exactly `ws://127.0.0.1:18792`.
- Check that the token matches what `artifice_redeem` returned (copy-paste exactly) and has not passed its 8-hour expiry.
**`artifice_cdp` returns "No client browser connected"**
- The extension is not connected. Check the extension icon — it should show a green indicator.
- Call `artifice_status` to check the connection state.
**`artifice_cdp` returns `CDP method not allowed`**
- The requested CDP method is not in the relay allowlist. Use an allowed method or update the relay allowlist in code.
**`artifice_cdp` returns an error about session**
- You have multiple tabs shared. Call `artifice_status`, find the `sessionId` for your target tab, and pass it explicitly.
---
## License
MIT
channels
Comments
Sign in to leave a comment