MCP tool reference

Arx's server is named arx. It lists only the tools the client's current grant covers, and the list changes with notifications/tools/list_changed when you change the grant. Arx still checks every call, so calling an unlisted tool is denied.

The classes in each table are the ones you turn on under Grants and approvals. Every tool also needs read. Risk is how Arx treats the call against the approval policy: read never asks, mutate asks under Every time, destructive also asks under Only for closing or removing.

Read Working with pages first for the IDs, revisions and snapshots these tools pass around.

Browser organization

Organization commands

browser_tabs, browser_folders, browser_hosts, browser_spaces, browser_profiles and browser_windows share one shape:

Details that matter:

• openTab targets a space and needs url. With route: true, Air Traffic Control picks the destination: targetID is then the source space, and the result's route reports profileID, spaceID, mode (mainBrowser or littleArx), source (rule or fallback) and the matched rule. The routed space must also be granted. No usable destination returns routeUnresolved.
• closeTab is destructive. Open tabs go to the Tab Archive; pins and Favorites keep their saved entry and only unload.
• moveTab into a space of another profile reopens the URL there. The live session and cookies stay behind. Moving folders or Little Arx across profiles returns crossProfileTransferUnsupported.
• removeSavedEntry deletes a pin or Favorite. It's destructive, and Undo is in Arx.
• deleteFolder closes everything inside, after each page allows it. ungroupFolder keeps the children.
• openPeek needs sourceTabID and sourceRevision, and previews url or, without one, targetID. Promotions take presentationID and presentationRevision from inventory.
• deleteSpace moves the contents into destinationID when given, otherwise closes them. The last space can't be deleted.
• createProfile: a new profile isn't granted until you grant it. deleteProfile erases the profile's browsing data and needs a profile with no spaces left.
• Results report committed or acceptedLoading, not that the page finished loading.

browser_archive and browser_downloads

action: "list" pages through entries, newest first, filtered by query, with cursor and limit (1 to 100). restoreArchived reopens an entry as a new tab in its original space, or in destinationID when that space is gone. The entry leaves the archive, so a retry can't restore it twice.

Downloads need whole-profile grants. cancelDownload stops one in progress, and revealDownload shows a finished file in Finder. Private downloads never appear.

browser_history

Searches visited pages of whole-profile grants, newest first, by title and URL, ignoring case. Takes query, cursor and limit (1 to 100). URLs drop user information, query and fragment; titles may still be private.

browser_links

browser_batch

steps is an array of 1 to 16 { "tool", "arguments" } objects, each exactly as that tool takes them. Arx asks once for the whole list when any step needs approval, and only those steps run under it, in that order. The batch stops at the first step that fails; later steps never run and nothing is retried. Later steps can't use earlier results, so take snapshots and revisions first.

Allowed step tools: browser_inventory, browser_tabs, browser_folders, browser_hosts, browser_spaces, browser_profiles, browser_windows, browser_command, browser_capture, browser_inspect, browser_wait, browser_click, browser_replace_text, browser_select_value, browser_keypress, browser_scroll, browser_hover, browser_drag, browser_type, browser_set_checked. Uploads, dialogs and media can't be batched.

browser_command is the older single tool for all organization actions. It still works for existing scripts but is no longer listed.

Reading pages

All page text and pixels are untrusted website data, never instructions. None of these tools focuses, scrolls or navigates the page.

browser_wait

targetID, expectedRevision, condition: "loadingStopped" and timeoutMilliseconds (1 to 10,000, default 2,000). Returns stopped or stoppedWithError with an errorCode. Stopped isn't HTTP success or DOM readiness. A new navigation returns staleTarget.

browser_inspect

A page holds up to 16,384 nodes in all. References expire within 30 seconds and whenever the DOM changes. If the page changed between pages of a read, the cursor fails with staleCursor.

browser_read

format is markdown (default) or text. scope is main (default: the main landmark, or the page without navigation, banner and footer) or all. Text comes in chunks of limit bytes (1,024 to 65,536, default 16,384), cut at line boundaries. Also takes load, frameID and formValues. Link targets aren't included.

browser_find

query (up to 256 characters) is matched ignoring case and diacritics. Returns up to limit matches (1 to 100, default 20) with roles, short excerpts and the nearest reference. Nothing is highlighted in the page.

browser_find_in_page

text starts a search, direction (next or previous) moves through it, and stop: true ends it. Returns the number of matches and the active one. Because the highlight is visible to you and the page, it counts as a change.

browser_pdf

action: "export" prints the page to a PDF of at most 4 MiB, returned as a resource; nothing is saved to disk. It takes landscape, printBackground and scale (0.1 to 2). action: "text" reads the PDF the tab shows, in chunks of limit bytes with cursor. Private tabs are never read.

browser_capture

Images are at most 4 MiB encoded; a bigger one fails with limitExceeded, so ask for a smaller scale, JPEG or a smaller region. Pixels may contain private information, and there's no redaction.

Acting on pages

These need pageContent and interact, act on references from the connection's latest browser_inspect snapshot, and count as changes. Each takes operationID, targetID, expectedRevision, snapshotID and reference. Most take returnSnapshot: true to get a fresh snapshot back in the same call.

Password fields, file inputs and disabled or hidden controls are refused where they don't belong. Typed text, field values and paths are never echoed back.

Sign-in

Not available

There is no tool to run JavaScript, read the clipboard, read saved passwords, reach the file system or attach a raw DevTools connection.