All articles

AI agents (MCP)

The desktop app includes an MCP server, so AI agents such as Claude Code, Claude Desktop or Cursor can work with your profiles. It is part of the Local API (Pro and higher) and uses the same API key.

Connect

  1. Turn on the Local API in Settings → Local API and save your API key there (create one in Dashboard → API keys).
  2. Add the server to your agent. In Claude Code:
claude mcp add --transport http owlxbrowser http://127.0.0.1:50380/mcp --header "Authorization: Bearer lak_your_key"

Other MCP clients that speak Streamable HTTP (Cursor and others): add a server at http://127.0.0.1:50380/mcp with the header Authorization: Bearer <your API key>. Use your own port if you changed it.

Apps that only start local commands (Claude Desktop)

Use the small bridge mcp-stdio-bridge.mjs from the examples folder (it needs Node.js 18 or newer and nothing else). It passes the app's messages to the MCP server above:

{
  "mcpServers": {
    "owlxbrowser": {
      "command": "node",
      "args": ["C:/path/to/mcp-stdio-bridge.mjs"],
      "env": { "OWLX_API_KEY": "lak_your_key", "OWLX_API_PORT": "50380" }
    }
  }
}

The server only listens on your computer (127.0.0.1) and refuses requests from web pages. On a server, start the app in headless mode and connect the same way.

Tools

ToolWhat it does
list_profilesProfiles with id, number, name, state, OS, proxy and tags (optional search)
create_profileNew profile with a fresh, consistent fingerprint; optional OS, proxy string, group and tags
start_profile / stop_profileOpens or closes a profile's browser; start returns its DevTools endpoint
list_runningProfiles open on this computer, with their endpoints
open_urlOpens an address in a running profile and waits for it to load
page_textThe current page's address, title and visible text
screenshotA picture of the current page
move_profilePuts a profile into a group (or out of it)
clear_cacheDeletes a stopped profile's cache (logins stay)
get_cookies / set_cookiesReads or adds a profile's cookies (needs the role permission "Export and import cookies")
list_proxies / check_proxySaved proxies (never their passwords) and a live check from your computer
list_groupsProfile groups
list_flows / run_flow / get_runYour RPA flows: list them, run one on profiles, follow its progress

In a team, the agent can do what your role allows, nothing more.

Profiles are real accounts: tell the agent what it may do, and keep an eye on it the first times.

A skill for coding agents

Coding agents (Claude Code, Codex, Cursor and others) write better scripts for OwlXBrowser when they know how the Local API works. Save the text below as .claude/skills/owlxbrowser/SKILL.md in your project (Claude Code), or paste it into your agent's instructions file (AGENTS.md, Cursor rules).

---
name: owlxbrowser
description: Drive OwlXBrowser antidetect profiles from scripts through its Local API (start/stop profiles, connect Playwright/Puppeteer/Selenium, manage profiles, proxies, tags, RPA flows). Use when writing automation that opens OwlXBrowser profiles.
---

# OwlXBrowser Local API

- Base URL: `http://127.0.0.1:50380` (the port is set in the app under API & Developers). Every request sends `Authorization: Bearer <API key>`; keys start with `lak_`. Never hard-code the key: read it from an environment variable (e.g. `OWLX_API_KEY`).
- The desktop app must be running and signed in (or started headless on a server). The API only answers on 127.0.0.1.
- Rate limits depend on the plan: on HTTP 429, wait for `Retry-After` seconds.

## Profiles
- `GET /v1/profiles?search=&group=&tag=` → `{ data: [...] }` (id, name, notes, engine, group_id, proxy_id, tags, status)
- `POST /v1/profiles` `{ name, template_id? ("chromium-windows", "chromium-macos", "cf-windows"…), group_id?, proxy_id?, tags?, notes? }`
- `PATCH /v1/profiles/{id}` · `DELETE /v1/profiles/{id}` · `POST /v1/profiles/{id}/move` `{ group_id }`
- `POST /v1/profiles/{id}/new-fingerprint` (closed profiles) · `GET /v1/profiles/{id}/user-agent`
- `GET|POST /v1/profiles/{id}/cookies` · `POST /v1/profiles/{id}/clear-cache`

## Open and automate
- `POST /v1/profiles/{id}/start` `{ headless?: boolean }` → `{ protocol, endpoint, debug_port, debugger_address }`
  - `protocol: "cdp"` (Chrome engines): Playwright `chromium.connectOverCDP(endpoint)`, Puppeteer `puppeteer.connect({ browserWSEndpoint: endpoint })`, Selenium `debuggerAddress = debugger_address`.
  - `protocol: "bidi"` (Firefox profiles): Puppeteer `puppeteer.connect({ browserWSEndpoint: endpoint, protocol: "webDriverBiDi" })`.
  - Use the existing context and pages; don't launch a new browser and don't change the user agent, viewport or timezone yourself (the profile's fingerprint already sets them consistently).
- `POST /v1/profiles/{id}/stop` · `POST /v1/profiles/stop-all` · `GET /v1/profiles/running` · `GET /v1/profiles/{id}/status`

## Proxies, groups, tags
- `GET|POST /v1/proxies`, `PATCH|DELETE /v1/proxies/{id}`, `POST /v1/proxies/{id}/check` — types: `http`, `https`, `socks5`, `ssh`. Passwords are never returned.
- `GET|POST /v1/groups`, `PATCH /v1/groups/{id}` · `GET|POST /v1/tags`, `PATCH|DELETE /v1/tags/{id}`

## RPA flows
- `GET /v1/flows` · `POST /v1/flows/{id}/run` `{ profile_ids: [...], options?: { concurrency, closeAfter, repeat, headless } }` → task; follow it with `GET /v1/tasks/{taskId}`.

## Scripts written for AdsPower or Dolphin{anty}
They work with the port changed and the API key added: AdsPower `/api/v1/browser/start|stop|active`, `/api/v1/user/*`, `/api/v1/group/*` and the v2 `/api/v2/browser-profile/*`, `/api/v2/browser-tags/*`, `/api/v2/proxy-list/*` routes; Dolphin `/v1.0/browser_profiles/{id}/start|stop`.

## Good practice
- Profiles are real accounts: act like a person (waits, scrolling), one script per profile at a time, and stop the profile when done.
- Handle errors: 401 wrong key, 403 plan or role, 404 unknown profile, 409 profile open elsewhere or busy, 422 invalid input.