Oya Browser docs
MCP tools reference
Every Oya Browser MCP tool with its parameters: analyze_page, navigate, click, type, press_key, screenshot, scroll, tabs, wait and the rest.
analyze_page
Analyzes the current page. Returns the full page with every interactive element numbered, written as TOON (the default), markdown or JSONL. Left out, format falls back to the server's OYA_PAGE_FORMAT, which is toon unless set.
analyze_page() // TOON, the default: fewer tokens
analyze_page({ format: 'markdown' }) // markdown
analyze_page({ format: 'jsonl' }) // one JSON object per lineReturns:
- Page metadata, URL, title, viewport size, scroll position
- Full page content with element tags like
[#5 button "Submit"]in markdown, or oneblocks[N]{id,region,kind,text,target,state}row per block in TOON, or one JSON object per block in JSONL - Element index, all elements listed with IDs, types, labels, visibility flags
analyze_page before using click or type. Element IDs only exist after analysis and reset on every call.navigate
Navigate the browser to a URL.
navigate({ url: "https://example.com" })analyze_page again, old element IDs are invalid on the new page.click
Click an interactive element by its ID number from analyze_page.
click({ element_id: 13 })The element was tagged with data-ac-id="13" during analysis, so the click resolves via a single querySelector.
type
Type text into an input element. Clears existing content first, then types character by character with realistic key events.
type({ element_id: 9, text: "hello world" })press_key
Press a keyboard key. Useful for submitting forms (Enter), dismissing dialogs (Escape), or navigating (Tab, arrows).
press_key({ key: "Enter" })Allowed keys: Enter, Escape, Tab, Backspace, Delete, Space, ArrowUp, ArrowDown, ArrowLeft, ArrowRight, Home, End, PageUp, PageDown. No modifiers and no F-keys; the desktop app's local port and the cloud allow the same list. For a combination such as Shift+Tab use key_chord.
screenshot
Capture the visible tab as a base64 PNG image.
screenshot()scroll
Scroll the page up or down.
scroll({ direction: "down", amount: 500 })| Param | Type | Description |
|---|---|---|
direction | "up" | "down" | Scroll direction |
amount | number (optional) | Pixels to scroll, default 500 |
Tab Management
list_tabs, open_tab, switch_tab and close_tab, along with read_elements, read_console, read_network and the rows marked per-browser under More tools, are not served by /mcp/pool.list_tabs
List all open tabs with ID, title, URL, and which is active.
list_tabs()open_tab
Open a new tab, optionally at a URL.
open_tab({ url: "https://gmail.com" })switch_tab
Switch to one of your own tabs; list_tabs marks them yours. Tabs the person or another agent is using are refused; use open_tab instead.
switch_tab({ tab_id: 2 })close_tab
Close a tab you opened with open_tab (default: your current tab). Tabs the person or another agent opened are refused; leave them open.
close_tab({ tab_id: 3 })wait
Wait for an element matching a CSS selector to appear on the page.
wait({ selector: ".results", timeout: 10000 })More tools
The rest of the tool set, one line each. Arguments in brackets are optional. Every tool is on a browser's own endpoint, /mcp/{BROWSER_ID}. The pool endpoint serves the ones that make sense on any browser; rows marked per-browser only, and the history, bookmarks and notifications group, need the browser's own endpoint.
Page actions
| Tool | Arguments | What it does |
|---|---|---|
find | query | The elements matching a description ("search box", "add to cart"), best first, with ids for click and type. |
read_elements | [selector], [limit] | The element index without the page text, same ids as analyze_page. Per-browser endpoint only. |
select_option | element_id, option | Choose an option of a native select by its text. |
hover | element_id | Move the mouse onto an element, for menus and tooltips that open on hover. |
edit_text | operation | Native select_all, undo or redo in the focused editor, using its own selection and undo history. Per-browser endpoint only. |
scroll_at | x, y, delta_x, delta_y | Scroll under a point, for nested panels and horizontal tables. Coordinates come from a screenshot. Per-browser endpoint only. |
handle_dialog | accept, [prompt_text] | Answer a confirm or prompt blocking the page. Alerts are answered automatically. |
go_back | none | Go back one page in the tab history and wait for the page. |
go_forward | none | Go forward one page and wait for the page. |
reload | none | Reload the tab and wait for the page. |
run_script | script | Run JavaScript that reads the page and returns JSON data, in an isolated world the page cannot see. It may not click, type, send requests or navigate. |
Mouse and keyboard
| Tool | Arguments | What it does |
|---|---|---|
click_coordinates | x, y | Click at a pixel position, when you know it from a screenshot. |
double_click | [element_id], [x], [y] | Double-click an element by id, or at a position. |
mouse_move | x, y | Move the cursor to a position without clicking. |
drag | from_x, from_y, to_x, to_y | Drag from one point to another: sliders, drag-and-drop, selecting text. |
keyboard_type | text | Type into whatever is focused, no element needed. |
key_chord | key | Press a key combination in the page, such as Shift+Tab or ControlOrMeta+a. Never a browser shell shortcut. Per-browser endpoint only. |
list_keyboard_shortcuts | none | The connected browser's own keyboard shortcuts, read-only, so you can explain them to the person. Per-browser endpoint only. |
Waiting and reading
| Tool | Arguments | What it does |
|---|---|---|
wait_for | [text], [url], [network_idle], [timeout] | Wait until text shows, the URL contains something, or the network goes quiet (the default). At most 20000 ms. |
read_console | [level], [pattern], [limit] | What the page logged. Oya browsers, per-browser endpoint only. |
read_network | [failed_only], [pattern], [limit] | The requests the page made. Oya browsers, per-browser endpoint only. |
start_trace | none | Start a bounded network and console trace on the active tab before reproducing an issue. Returns a trace_id. No headers, cookies or bodies are kept. Per-browser endpoint only. |
read_trace | trace_id, [after], [limit] | Read the next page of the trace, in order. Pass next_cursor as after to continue. Per-browser endpoint only. |
stop_trace | trace_id, [after], [limit] | Stop the trace and read its final page. Per-browser endpoint only. |
Sign-in and CAPTCHA
| Tool | Arguments | What it does |
|---|---|---|
solve_captcha | none | Clear a CAPTCHA with the configured solver. |
sign_in | none | Sign in with the persona's stored credentials for the site. Credentials never reach you. |
complete_mfa | none | Enter a one-time code from the persona's factors. The code never reaches you. |
list_saved_logins | none | The sites the persona has a saved login for, username only, so you know whether sign_in can fill the form. |
History, bookmarks and notifications
| Tool | Arguments | What it does |
|---|---|---|
search_history | [query], [limit], [offset] | Search this profile's recent history, newest first. |
list_bookmarks | [query], [limit], [offset] | List or search this profile's bookmarks. |
add_bookmark | url, [title] | Save or update a bookmark. Repeating the call never removes it. |
remove_bookmark | url | Remove one bookmark by exact URL, when the person asks. |
clear_history | confirm | Clear this profile's stored history, only when the person asked. Bookmarks, cookies and closed tabs stay. |
list_closed_tabs | none | This profile's recently closed tabs, newest first. |
reopen_closed_tab | none | Reopen the most recently closed tab. Each call reopens the next one. |
list_notifications | [unread_only], [limit], [offset] | This profile's toolbar notification inbox, newest first. Reading does not mark anything read. |
mark_notifications_read | ids | Mark the given notifications read, when the person asks to acknowledge them. |
dismiss_notification | notification_id, confirm | Dismiss one notification, at the person's request. Never clears the inbox. |
Playbooks and tasks
| Tool | Arguments | What it does |
|---|---|---|
list_playbooks | none | The playbooks saved on this key. |
run_playbook | name, [variables] | Replay one with its variables. A broken step is finished by the agent. |
run_task | task, [data] | Hand a whole task to Oya's own agent and get DONE: or FAILED: back. Uses the key's configured model. |
Pool
| Tool | Arguments | What it does |
|---|---|---|
start_browser | [persona], [provider], [name], [url] | Start a browser on your key and make it the one every other tool drives. Persona is an id, "auto" or "default". Billed until stopped. |
stop_browser | [browser_id] | Stop a browser and release its session. Defaults to the one being driven. |
pool_status | none | Pool size and connected browsers. |