Browser Orchestrator Control

Publication package: browser-orchestrator-control-0.2.3.zip

Overview

Use this skill to operate Browser Orchestrator as a headed Browser Node behind MCP Relay. Browser Orchestrator pairs with Relay using a short-lived pairing token, stores issued node credentials locally, then keeps an outbound authenticated worker WebSocket open for assigned browser tasks.

The headed browser stays local. Login, MFA, CAPTCHA, and sensitive verification steps remain manual.

Connection

Token types:

• MCP_RELAY_PAIRING_TOKEN: short-lived token used only to pair this Browser Node through POST /api/nodes/pair.
• node_secret: issued by pairing and stored in .local/relay-node.json; used only by the Browser Node worker WebSocket.
• MCP_RELAY_MCP_TOKEN: bearer token used by desktop Agents or @tpxipsterliu/mcp-connect to call the MCP Relay Streamable HTTP MCP endpoint at /mcp.

Token source:

• The Relay operator sets MCP_RELAY_MCP_TOKEN on the MCP Relay server before starting npm.cmd run mcp:http.
• The Relay operator sets or issues MCP_RELAY_PAIRING_TOKEN for Browser Node pairing before starting the worker-channel server.
• The current MCP Relay console does not mint MCP API tokens. If no MCP_RELAY_MCP_TOKEN was configured on the relay server, there is no MCP auth token to use yet.

Installation model:

• Install this Skill on the desktop Agent machine that will talk to MCP Relay or control a local Browser Orchestrator MCP fallback.
• Run Browser Orchestrator itself on the headed Browser Node workstation where the real browser, profile, extension, and manual login happen.
• If the desktop Agent and Browser Node are different machines, the Agent should use the mcpRelay connector. Do not expect local Browser Orchestrator commands to work on the Agent machine unless Browser Orchestrator is also installed there.
• Keep pairing and worker startup on the Browser Node workstation; keep MCP Relay /mcp connector setup on the Agent machine.

Preferred Relay mode:

$env:MCP_RELAY_URL = "https://mcp-relay.cloudplus.im"
$env:MCP_RELAY_WS_URL = "wss://mcp-relay.cloudplus.im/ws/nodes"
$env:MCP_RELAY_PAIRING_TOKEN = "replace-with-one-time-token"
npm.cmd run relay:pair
npm.cmd run relay:worker

The pairing command writes .local/relay-node.json by default. Do not ask the user to paste the issued node_secret into chat. After pairing, start the worker with npm.cmd run relay:worker; it sends node.hello, heartbeats, task progress, logs, completion, and failure events to Relay.

Electron debug console mode:

1. Open the MCP Relay Worker panel.
2. Fill Relay URL, Worker WS, Pairing Token, credentials path, node metadata, capacity, capabilities, and optional capture selector.
3. Click Pair Relay.
4. Click Start Relay after pairing.

MCP Relay connector mode for desktop Agents:

Use @tpxipsterliu/mcp-connect only for connecting a desktop Agent to a remote Streamable HTTP MCP Relay endpoint, not for Browser Node worker login.
The token for this mode must be the Relay MCP auth token configured on the relay server as MCP_RELAY_MCP_TOKEN; do not use MCP_RELAY_PAIRING_TOKEN or the saved Browser Node node_secret here.

npx @tpxipsterliu/mcp-connect init
npx @tpxipsterliu/mcp-connect create mcpRelay `
  --url https://mcp-relay.cloudplus.im/mcp `
  --env-header Authorization=MCP_RELAY_MCP_AUTH_HEADER
$env:MCP_RELAY_MCP_AUTH_HEADER = "Bearer <MCP_RELAY_MCP_TOKEN>"
npx @tpxipsterliu/mcp-connect doctor mcpRelay

Do not use https://mcp-relay.cloudplus.im/api/mcp; /api/* belongs to the Web Console and worker REST API namespace.

If a desktop MCP connector opens a browser authentication window for https://mcp-relay.cloudplus.im/mcp, the Relay Web service may redirect the user to employee login and then to /mcp/auth. That confirms the Web session is ready for same-origin connector flows. Connectors that do not preserve the Web session cookie should still use the explicit Authorization: Bearer <MCP_RELAY_MCP_TOKEN> header through mcp-connect.

Desktop agents can launch the connector with:

npx @tpxipsterliu/mcp-connect run mcpRelay

Local Browser Orchestrator MCP fallback:

Development command:

npm.cmd run mcp

Built command after npm.cmd run build:

node dist/mcp/server.js

Packaged command:

browser-orchestrator-mcp

Workflow

1. Prefer Relay mode when the user wants this machine to receive tasks from MCP Relay.
2. Pair once with a short-lived MCP_RELAY_PAIRING_TOKEN; store credentials under .local/relay-node.json.
3. Start the Relay Worker and confirm it reports connected.
4. For assigned tasks, navigate only to explicit HTTP(S) target boundaries and keep the browser headed.
5. If login, MFA, CAPTCHA, or manual setup is needed, ask the user to complete it in the browser before continuing.
6. Use local MCP tools directly only for debugging or when the user asks for local browser control instead of Relay task routing.
7. Call page_screenshot or Relay screenshot behavior when visual evidence or debugging is useful.
8. Use the configured capture selector for extension capture; otherwise leave the headed browser inspectable and request manual capture.

Tools

Relay commands:

• relay:pair: pair this Browser Node with MCP Relay using MCP_RELAY_PAIRING_TOKEN.
• relay:worker: maintain the authenticated worker WebSocket to MCP Relay.

Local MCP tools:

• browser_start: start the headed browser with persistent profile and default extension path.
• browser_status: report session, run directory, URL, and extension availability.
• browser_stop: close the active browser session.
• page_goto: navigate to a URL.
• page_snapshot: return structured page state and visible body text.
• page_click: click an element by Playwright selector.
• page_fill: fill an input-like element by Playwright selector.
• page_wait: wait by time or selector.
• page_screenshot: save a screenshot into the active run directory.
• capture_trigger: trigger the scraping extension through a known selector or ask for manual capture.

Safety Rules

• Keep login, MFA, CAPTCHA, and verification steps manual.
• Do not ask the user for passwords or secret tokens in chat.
• Do not print or commit .local/relay-node.json, node secrets, pairing tokens, cookies, or browser profiles.
• Do not bypass site access controls.
• Ask for confirmation before destructive, paid, account-changing, or high-volume actions.
• Keep scraping targets explicit and user-approved.
• Use the extension capture path instead of inventing a separate scraper unless the user explicitly requests otherwise.

Capture Behavior

If capture_trigger returns mode: "manual_required", tell the user to click the extension capture button in the headed browser. Continue only after the user confirms capture finished.

If the extension injects a page button and the selector is known, call capture_trigger with selector.