Connect an agent

Register the companion with Claude Code, Codex, OpenCode, Cursor, Kilo or Antigravity over stdio.

Every stdio client runs the same command. It fetches the browspark-mcp package from npm on first run and caches it; @latest keeps it current. If the client cannot find bunx, use the full path to the executable (~/.bun/bin/bunx by default).

bunx browspark-mcp@latest

Add --port 9224 (or any port) if 9223 is taken by something that is not another companion, and set the same port in the dashboard’s Settings. The dashboard’s Overview page generates these snippets with the port you configured.

Claude Code

claude mcp add --transport stdio --scope user browspark -- bunx browspark-mcp@latest

--scope user makes it available in every project. Start a new session and run /mcp to check the connection. Claude Code MCP docs.

Codex

codex mcp add browspark -- bunx browspark-mcp@latest

Codex writes the server into ~/.codex/config.toml. Restart Codex, then check with /mcp in the CLI. Codex MCP docs.

OpenCode

Add to ~/.config/opencode/opencode.json (global) or opencode.json in a project:

{
  "mcp": {
    "browspark": {
      "type": "local",
      "command": ["bunx", "browspark-mcp@latest"],
      "enabled": true
    }
  }
}

Restart OpenCode and run opencode mcp list. OpenCode MCP docs.

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "browspark": {
      "type": "stdio",
      "command": "bunx",
      "args": ["browspark-mcp@latest"]
    }
  }
}

Restart Cursor and check Customize → MCP. Cursor MCP docs.

Kilo

Add to ~/.config/kilo/kilo.jsonc:

{
  "mcp": {
    "browspark": {
      "type": "local",
      "command": ["bunx", "browspark-mcp@latest"],
      "enabled": true
    }
  }
}

In the Kilo extension open Settings → MCP and check that Browspark is enabled. Kilo MCP docs.

Antigravity

In the Agent panel open … → MCP Servers → Manage MCP Servers → View raw config and add:

{
  "mcpServers": {
    "browspark": {
      "command": "bunx",
      "args": ["browspark-mcp@latest"]
    }
  }
}

Save, then confirm Browspark is enabled in MCP management. Antigravity MCP docs.

Clients that take a URL instead of a command are covered in HTTP endpoint. Running several of these clients at once is fine: see Multiple agents.

Checking the connection

Ask the agent to call browser_status. A healthy answer looks like this:

Companion bridge: ws://127.0.0.1:9223
You are agent "claude-code".
Extension mode: connected to Chrome/152.0.0.0 (extension v0.2.8). Tabs below are that browser's tabs. The user can open DevTools (F12) on a shared tab to watch your console, network, debugger, and emulation work in the standard panels; that does not conflict with you.
Developer mode: not running. Only launch it (browser_session) if the user asks for a separate browser or a tool says an operation needs it; otherwise work in the user's shared tabs.
Usable tabs (2) across all windows; select a listed tabId:
  [1731] extension Example Domain — https://example.com (window 1)
  [1740] extension (new tab: navigate to a website) (untitled) — chrome://newtab (window 1)

If it says NOT CONNECTED, follow the pairing instructions it prints. The agent’s name as reported by the MCP client (for example claude-code or opencode) shows up in the dashboard’s activity log and next to the tabs that agent opened.

Naming and scope

The companion names each connected agent after what the MCP client calls itself during the MCP handshake. That name is used for tab ownership, recordings and the activity log. Two sessions of the same client share a name but still get separate tab ownership because each MCP connection is a distinct client.