browser-bridge-setup

Browser Bridge Setup

What gets installed

1. MCP server — exposes 29 browser tools to the agent (stdio via Grok, or HTTP gateway)
2. WebSocket bridge — local relay on 127.0.0.1:18793 (auto-started)
3. Chrome extension — user loads unpacked from extension/dist (not from Chrome Web Store)

Setup flow (run in order)

1. Token

bash ${CLAUDE_PLUGIN_ROOT}/scripts/setup-token.sh

Stored at ${CLAUDE_PLUGIN_ROOT}/.bridge-token (gitignored). Copied to clipboard when wl-copy, xclip, or xsel is available.

2. Build extension (injects token)

cd ${CLAUDE_PLUGIN_ROOT} && bun install && bun run build:extension

3. Load in Chrome

• chrome://extensions → Developer mode → Load unpacked → ${CLAUDE_PLUGIN_ROOT}/extension/dist
• Pin the toolbar icon

4. Auth

The build injects the token into the background bundle. If auth fails:

1. Open extension popup
2. Paste token → Save & reconnect
3. Or reload extension on chrome://extensions after rebuild

5. Verify

bash ${CLAUDE_PLUGIN_ROOT}/scripts/setup-wizard.sh --check

Or use MCP bridge_status — need all three: bridgeReachable, extensionConnected, extensionAuthenticated.

After token change

Always:

1. bash ${CLAUDE_PLUGIN_ROOT}/scripts/setup-token.sh (or --regenerate)
2. bun run build:extension
3. Reload extension in Chrome
4. Restart bridge if using HTTP gateway: stop-gateway.sh then start-gateway.sh

Optional HTTP gateway

For clients that need HTTP MCP instead of stdio:

bash ${CLAUDE_PLUGIN_ROOT}/scripts/start-gateway.sh
# MCP endpoint: http://127.0.0.1:18794/mcp

Agent behavior during setup

• Run /browser-bridge-setup command for the full walkthrough
• Explain each step in plain language; don't dump all steps at once
• Use setup-wizard.sh --check for programmatic health
• On success, offer a smoke test with list_tabs