32 tools. One endpoint.

Connect

The hosted endpoint is https://browselenium.online/mcp (streamable HTTP). The browser runs on our infrastructure; your process only sends tool calls and receives JSON, images and text back.

// opencode — opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "browselenium-online": {
      "type": "remote",
      "url": "https://browselenium.online/mcp"
    }
  }
}

// Claude Code — .mcp.json
{
  "mcpServers": {
    "browselenium-online": {
      "type": "http",
      "url": "https://browselenium.online/mcp"
    }
  }
}

Self-hosting: the same 32 tools run locally from this repository (uv run browselenium-online with BROWSELENIUM_ONLINE_API_KEY set, or the full hosted stack via BROWSELENIUM_ONLINE_HOSTED=1). Tool signatures are identical; see the README and docs/BACKEND.md for deployment details.

Authentication

If the server has an API key configured, every browser tool errors until you call authenticate(key=...) with the key from your dashboard. The key is shown once at signup and can be rotated any time (rotation invalidates the old key immediately).

• Free calls: authenticate, get_skill and browser_status never consume quota.
• Key storage for agents: save the key as a single line in ~/.config/browselenium.online/api-key (mode 600) and reuse it on later sessions instead of asking the user again.
• Sessions are per connection: in hosted mode, one active browser per API key. A second connection must stop the running session first.

Core workflow

• authenticate(key="bso_...") — once per session; returns a quickstart.
• browser_start(headless=true) — launch (or replace) the cloud browser.
• navigate(url, wait_seconds=5..10) — load a page; give bot checks time to resolve. Check challenge_detected in the result.
• Read and act — page_structure / get_text / find, then click / type_text / execute_js as needed.
• browser_stop() — always stop when done; a leaked session pins a browser process and burns its lifetime.

Session tools

Reading tools

Acting tools

State tools

Tiers & metering

Every browser tool call consumes one request of the daily quota; authenticate, get_skill and browser_status are free. Quota resets at midnight UTC. The browser is killed after the tier's maximum lifetime — start a new one with browser_start.

Errors & limits

• Quota exhausted — tools error until the next UTC day or an upgrade. browser_status shows usage.
• Lifetime exceeded — the browser is killed at the tier's max life; just browser_start again.
• Challenge detected — challenge_detected: true in a navigate result means slow down, not push harder: space retries at least 5 s apart, prefer a longer wait_seconds. Standalone installs can also retry with headless=false or a residential proxy.
• Session on another connection — hosted mode allows one active browser per key; stop it on the other connection (or wait for it to end) before starting again.
• Blocked destination — hosted browsing is public-web only: non-http(s) URLs and internal/loopback addresses are refused and flagged.

Examples

Read a page

authenticate("bso_...")
browser_start(headless=true)
navigate("https://target.example/pricing", wait_seconds=5)   # check challenge_detected
page_structure()
browser_stop()

Log in and keep the session

navigate("https://app.example/login")
find("input")
type_text("#email", "[email protected]")
type_text("#password", "••••••••", press_enter=true)
get_text()                          # verify you are in
cookies = get_cookies()             # save the JSON for next time
browser_stop()

# next run: navigate to the site, then set_cookies(saved) — still logged in

Extract a table in one round-trip

execute_js("return JSON.stringify({
  headers: [...document.querySelectorAll('table th')].map(t => t.textContent.trim()),
  rows: [...document.querySelectorAll('table tbody tr')].map(tr =>
    [...tr.children].map(td => td.textContent.trim()))
})")

More workflows — passing bot checks, SPA handling, search, dropdowns — live in the skill: call get_skill() after authenticating, or read agent-install.md to set up your agent in one paste.