Assistants and MCP

MCP tool reference

Every tool Arx's MCP server offers, the access classes it needs, and its main parameters.

This page is a first draft. It may change before the public beta.

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

ToolNeedsRiskWhat it does
browser_inventoryreadreadLists granted spaces, folders, pins, Favorites and tabs, with IDs and revisions. Never loads or focuses pages.
browser_tabsorganizemutate, destructiveOpen, select, navigate, reload, go back or forward, stop, close, pin, unpin, move and favorite tabs.
browser_foldersorganizemutate, destructiveCreate, rename, move, ungroup and delete folders.
browser_hostsorganizemutateOpen Peek and Little Arx, and promote them to tabs.
browser_spacesbrowserAdmin to change, read to listmutate, destructiveList, create, rename, re-theme, recolor, reorder, delete and show spaces.
browser_profilesbrowserAdmin to change, read to listmutate, destructiveList, create, rename, recolor and delete profiles.
browser_windowsread to list, organize to changemutateList windows, focus one, and open, swap or close Split View of up to four tabs.
browser_archiveread to list, organize to restoremutateSearch the Tab Archive and restore an entry.
browser_historyhistoryreadSearch visited pages.
browser_downloadsdownloadsmutateList downloads, start one, cancel one, show one in Finder.
browser_linksreadreadClean a link, apply a Proxy Link rule, or resolve a bang. Nothing is opened.
browser_batchthe classes of its stepsthe highest of its stepsUp to 16 steps under one approval.
browser_runread, plus each step's own classeseach step's ownA script that calls the tools as functions, for steps that use earlier results.

Organization commands

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

Parameter
actionThe action name, from the list below. Spaces, profiles, windows, archive and downloads also take list.
operationIDA fresh UUID for every change. Never retry after a disconnect.
targetID, expectedRevisionThe item to act on and its current inventory revision.
destinationID, destinationRevisionWhere a move, pin or restore goes.
url, name, icon, themePer action. theme is light, dark or system.
appearance, clearAppearanceFor setSpaceAppearance and setProfileAppearance. See below.
focustrue to bring the result forward. New tabs don't focus otherwise. Peek and Little Arx require it.
ToolActions
browser_tabsopenTab, selectTab, navigate, reload, back, forward, stop, closeTab, pinTab, unpinTab, moveTab, addFavorite, removeFavorite, updateSavedURL, removeSavedEntry
browser_folderscreateFolder, renameFolder, moveFolder, ungroupFolder, deleteFolder
browser_hostsopenPeek, openLittleArx, promotePeekToTab, promotePeekToLittleArx, promoteLittleArx
browser_spaceslist, createSpace, renameSpace, setSpaceTheme, setSpaceAppearance, moveSpace, deleteSpace, selectSpace
browser_profileslist, createProfile, renameProfile, setProfileAppearance, deleteProfile
browser_windowslist, openSplit, swapSplit, closeSplit, focusWindow

Details that matter:

  • openTab always opens a new tab, never one of the person's. With Arx's agent tabs feature flag on, a tab your client left on the same page in an earlier connection is taken over instead: the result is committed with that tab's targetID, and the page isn't loaded again. See Tabs an assistant opens.
  • 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.
  • openSplit targets a tab and shows it beside the current page. With splitTabs, one to three more {id, revision} tab items, it makes a Split View of 2 to 4 tabs of the target's space instead, the target first, with equal panes. The split's tabs share the target's place in the sidebar, so each other tab moves next to the target: beside an open tab a pinned tab is unpinned, beside a pinned tab, or in its folder, an open tab is pinned there, and a tab of another space of the profile moves over. A Favorite joins and stays in Favorites. orientation is horizontal (side by side, the default) or vertical (stacked). Tabs leave any split they were in. A fifth tab, a Favorite as the target, or a window too small for the panes returns invalidRequest. swapSplit reverses the panes.
  • 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.
  • setSpaceAppearance and setProfileAppearance change the window chrome's tint and film grain for one space or profile, the same way Settings does. appearance is an object of the fields to choose: theme (light or dark), tintHue (0 to 360 degrees), tintIntensity (0 to 1), grainEnabled, grainIntensity (0 to 1), grainSize (1 to 3), accentColor (a preset such as red or teal, or #RRGGBB; see Accent color), matchesSite (true or false: whether to match the site) and gradient ("plain" for the tint's own, or { "stops": [{ "hue": 30, "intensity": 0.5 }], "angle": 135 } with one or two more colors). A field set to null (or theme: "system") goes back to following the profile, or for a profile, Settings. Fields you leave out stay as they are. clearAppearance: true clears the whole override first. Listed spaces and profiles show their own appearance and a resolvedAppearance, which is what their window actually shows.
  • 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. startDownload targets a profile from browser_profiles and takes an http or https url. Arx shows you the URL and asks first (see When Arx asks). The file goes to your Downloads folder, with the same prompts and safety checks as a download you start yourself, and the result's targetID is the new download's ID once it has started. List downloads to follow its progress. 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.

kindInputReturns
cleanurlThe link without tracking parameters. Sensitive parameters are kept.
proxyurlThe link after your first matching Proxy Link rule.
bangquery, such as !w swiftThe destination URL: your search shortcuts first, then the 13,000+ bundled bangs.

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_run

For loops and for steps that use what an earlier step returned: open each search result, fill a form from what was read, read a list until a row shows up. code is JavaScript that runs in Arx's helper on your Mac, never in a page. It reaches the browser only through the tools:

  • call("browser_click", { ... }) calls any tool, and each tool is also a function without its browser_ prefix, such as click({ ... }), read({ ... }) or history({ ... }). A step returns the tool's result object; a failed step throws an error whose code is the tool's error code.
  • Every step is that tool call. It goes through the same grant, the same approval and its own operationID as if the assistant called the tool itself. A step that needs your approval waits inside the run, and Arx shows the same request.
  • uuid() makes an operationID, sleep(ms) waits up to 20 seconds, console.log prints, and keep is an object that lasts from one run to the next.

A run takes at most 200 steps and timeoutSeconds (1 to 600, default 60), including time spent waiting for you, and an assistant runs one at a time. It answers with the script's returned value, what it printed as output (outputLimit bytes, 256 to 32,000, default 8,000) and a log of the tools it called. Screenshots and PDFs that its steps take come back with the result; if they don't all fit, the newest are kept. If the run is cancelled or reaches timeoutSeconds during a step, Arx stops that step and the log says so. The script itself can only compute: it has no network, timers or files.

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

Reading pages

ToolNeedsWhat it does
browser_waitreadWaits up to 10 seconds (default 2) for the current page to stop loading.
browser_inspectpageContentA semantic snapshot: text, roles, names and references you can act on.
browser_readpageContentThe page as Markdown or plain text.
browser_findpageContentFinds text in a snapshot and returns references to it.
browser_find_in_pagepageContent, interactChromium's find bar: highlights matches in the page. Risk: mutate.
browser_pdfpageContentExports the page to PDF, or reads the text of a PDF the tab shows.
browser_capturescreenshotsA PNG or JPEG screenshot.

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

Parameter
targetID, expectedRevisionAn ordinary HTTP(S) tab.
limitNodes per page, 1 to 512, default 100. Pass nextCursor alone (as cursor) for the next page.
loadtrue loads an unloaded tab in the background first, waiting up to 10 seconds: a saved tab that hasn't loaded yet, or one Arx unloaded to save memory.
frameIDRead a child frame, from an iframe node's frame.
formValuestrue adds values of eligible controls. Password, file, hidden, payment and one-time-code fields are always left out.
boundstrue adds element bounds in viewport points, usable as a capture region.
maximumTextBytesText per page, up to 65,536.

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

Parameter
modeviewport, region, fullDocument or element
region{ x, y, width, height } in viewport points, from the top left
snapshotID, referenceFor element, from a snapshot read with bounds: true
scale0.1 to 1, default 1
formatpng or jpeg; quality 0 to 1, default 0.8
offscreentrue captures a loaded background tab without showing it. Not for fullDocument.
savetrue asks you in Arx where to save the image. The assistant only learns the file name, or that you declined.

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. A click, key or typed line break that pays, sends, posts or deletes asks you every time, whatever the policy; see What counts as paying, sending, posting or deleting. Each takes operationID, targetID, expectedRevision, snapshotID and reference. Most take returnSnapshot: true to get a fresh snapshot back in the same call.

ToolWhat it does
browser_clickActivates a reference. With x/y, clickCount (1 to 3) or modifiers (shift, option, command), sends a real mouse click instead.
browser_typeFocuses a field and types text (1 to 1,024 bytes) as real key events. A line feed presses Enter. Refuses password fields.
browser_replace_textReplaces a whole text field's value (up to 32,768 bytes). Not typing.
browser_select_valuePicks one option by exact value, or several with values (up to 64) in a multiple select.
browser_set_checkedSets a checkbox or radio to checked true or false.
browser_keypressPresses one key, optionally with modifiers (shift, control, option, command). Browser and system shortcuts never run.
browser_scrollScrolls the nearest scrollable container of a reference on one axis (horizontal, vertical) by deltaCSSPixels (−8,192 to 8,192).
browser_hoverMoves the real pointer over a reference or point. Doesn't use up the snapshot.
browser_dragDrags from a reference or point to toReference or toX/toY, in steps (1 to 32, default 8).
browser_uploadAnswers a file chooser the page just opened with absolute paths (up to 32), or cancels it with an empty list. Needs files, and asks you every time.
browser_dialogread the page's alert, confirm, prompt, before-unload dialog or permission request; accept (asks you every time) or dismiss it with its token.
browser_medialist media sessions, then play, pause, seek (with seconds), enterPictureInPicture or exitPictureInPicture with a session token; mute and unmute a tab; read the position once. Needs interact only.

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.

Settings

ToolNeedsRiskWhat it does
browser_settingsbrowserAdminread, mutate, destructiveReads and changes listed preferences, Air Traffic Control rules, search shortcuts, keyboard shortcuts, and a profile's extensions, site permissions and zoom.

action: "read" with a section returns that section and its revision:

sectionWhat you get
preferencesEach setting the assistant may change, with its value and its type: a boolean, a choice (with the allowed values) or a number (with its range). Also rows: every row Settings' search finds, with its title, path and who may change it (see Who may change a setting).
routingYour rules in the order Arx tries them, and the fallback. Rules that send links to a profile or space outside the grant are left out and counted in hiddenRules.
searchShortcutsYour search shortcuts (your own bangs).
keyboardShortcutsEvery command's shortcut, and whether it's still the default.
extensionsThe extensions of profileID, and canInstall: whether installExtension is offered. Needs a whole-profile grant.
sitePermissionsprofileID's default for each permission (with the choices it takes and whether it's managed), and each site's own settings: origin, permission, setting, managed. Needs a whole-profile grant.
zoomprofileID's default page zoom and each site's (host, factor, where 1 is 100%), with the minimum and maximum. Needs a whole-profile grant.

action: "testRoute" with a url (and sourceSpaceID for rules that open in the current space) tells the assistant where Air Traffic Control would open the link, without opening anything.

Every other action is a change. It takes a fresh operationID and the section's revision as expectedRevision; if you changed that section in the meantime, it fails with staleTarget. Changes follow your approval policy, can't be part of a batch, go through the same steps as changing it yourself in Settings, so Settings shows it at once, and return the section's new contents.

actionParameters
setPreferencesvalues: an object of settings from the preferences section, such as { "warnsBeforeQuitting": false, "tintHue": 120 }. matchesSite is Match site's default for every profile and space.
saveRoutingRulerule: name, host, includesSubdomains, scheme, port, pathPrefix and destination (scope: currentSpace, profile or space, with its id; mode: mainBrowser or littleArx). Pass the rule's id to edit it; leave it out to add one.
deleteRoutingRule, moveRoutingRule, setRoutingRuleEnabledruleID, plus offset (-1 earlier, 1 later) or enabled. Deleting is destructive.
saveSearchShortcutshortcut: keyword, name, template with {query}, and an optional homepage. replacing names the keyword it replaces.
deleteSearchShortcut, setSearchShortcutEnabledkeyword, plus enabled. Deleting is destructive.
setKeyboardShortcutcommand and shortcut: { "key": "k", "modifiers": ["command", "shift"] }, or null to remove it.
resetKeyboardShortcutcommand. Restores its default.
setExtensionEnabledprofileID, extensionID and enabled.
installExtensionprofileID and the Chrome Web Store extension as extensionID (its 32-letter ID) or url (its page, such as https://chromewebstore.google.com/detail/…/<id>). Always asks you, in the install review, and waits for your answer. The result's installation.outcome is installed, declined, alreadyInstalled (nothing to review) or failed, with a reason.
setSitePermissionprofileID, permission (camera, microphone, location, notifications, popups or clipboard), origin (such as https://meet.google.com; leave it out to change the default) and setting (allow, block or ask, or null to remove the site's own setting). Allowing a site anything but pop-ups always asks you.
setSiteZoomprofileID, host (leave it out for the default) and factor, from 0.25 to 5, or null to remove the site's own zoom.
undoundoOperationID: the operationID of the assistant's own earlier setPreferences. Puts those settings back as they were, and takes the preferences section's revision. If you or anything else changed one of them since, it fails with staleTarget and changes nothing. Each change can be undone once, and Arx remembers the last 32.

Who may change a setting

Every row in Settings is one of three kinds, and the rows list says which:

accessWhat it means
agentThe assistant may change it: its keys in setPreferences, or its section's actions (Air Traffic Control, search shortcuts, keyboard shortcuts, extensions). Plain switches and choices, such as Haptics, Sound, Theme, New tabs or Sidebar position, are here.
userOnly you change it, in Settings: privacy and security, passwords and autofill, profiles, the assistant's providers and access, developer mode, updates, your default browser and the app icon, and how much memory and battery Arx uses.
uiNothing to set: a pane, a section heading, or a button that only shows something.

Every new row in Settings is given one of these before it ships.

What Arx refuses:

  • Security settings, developer mode and assistant access are never readable or writable: protectedSetting.
  • A value outside its setting's type or range: invalidValue.
  • A keyboard shortcut another command already uses: shortcutConflict, unless the call passes replace: true, which takes it from that command, like Replace in Settings. A search keyword that's already taken is also shortcutConflict.
  • Shortcuts macOS keeps for editing and windows, such as ⌘C or ⌘Z: shortcutReserved.
  • A routing rule that would send links outside the grant, or a rule the assistant can't see: denied.
  • An extension whose new permissions are waiting for your review can only be turned on by you, in Settings.
  • installExtension when this Arx can't install from the Chrome Web Store (canInstall is false): installationUnavailable. While the assistant runs unattended: userActionRequired. While the Extensions sheet is in the middle of another install or update: busy.
  • A site permission each permission doesn't take (pop-ups take no ask, and a default is only ask or block, or allow or block for pop-ups), or an origin that isn't an http or https site: invalidValue.
  • A site setting your organization, an extension or parental controls decide, or a private profile: unsupported.

Developer tier

Off unless you turn on developer mode and give the client script or devtools. Without developer mode both tools answer developerModeRequired. Both act on one granted tab of an ordinary profile, never a private window, and both accept "focused".

ToolNeedsRiskWhat it does
browser_evaluatescriptmutate, consequentialRuns JavaScript in the tab and returns what it returns, as JSON. A script that clicks, submits or sends always asks.
browser_logsdevtoolsreadKeeps and reads the tab's console messages and finished network requests.

browser_evaluate

script is the body of an async function: use return, and await works. Pass a fresh operationID, targetID, expectedRevision, and optionally maximumResultBytes (1,024 to 262,144, default 65,536) and timeoutMilliseconds (100 to 30,000, default 10,000).

The script runs in a separate JavaScript world of the tab's main frame. It sees and can change the page's DOM, and its fetch goes out as the page, with your session, but it doesn't share the page's own variables. A script can do anything you can do on that site. In that world:

  • document.cookie is empty and cookieStore isn't there.
  • Password fields, and fields for card numbers, card codes and one-time codes, read as empty, even if the script changes their type.
  • new FormData(form), new PasswordCredential(form) and navigator.credentials refuse.
  • Any cookie value of the page that still turns up in the result, for example because the site printed it into the page, comes back as [redacted].

The result has an outcome: value (with value), undefined, unserializable (with detail), exception or syntaxError (with error: name, message, and line for a syntax error). A value larger than maximumResultBytes fails with limitExceeded. A script that's still running after the timeout reports timedOut, though it may keep running in the page. If the page navigates, the call reports staleTarget.

Under Every time, each script asks you and shows its full text, even while scoped commands are allowed for 15 minutes. It can't be part of a batch.

browser_logs

actionWhat it does
startStarts keeping the tab's console messages and finished requests: up to 500 of each, newest kept. Nothing from before start is kept.
console, networkReturns up to limit entries (1 to 200, default 50) after the sequence number after (0 starts from the oldest kept), with next to pass as after next time and dropped, the entries that were no longer kept.
requestsWith networkDetails, after start with details: true: requests with their headers and bodies. bodyBytes (0 to 32,768, default 4,096) cuts each body; 0 leaves them out.
harThe same requests as a HAR 1.2 log.
stopStops and drops the logs.

Console entries have level, message, source, line and mainFrame. Network entries have method, url, status, type (such as document, script, image, or empty for fetch), mimeType, cached, bytes and an error such as ERR_NAME_NOT_RESOLVED. They never include headers, cookies or bodies. URLs lose any user name, password and fragment, and query values whose names suggest credentials (token, key, secret, password, session, code, state and similar) read redacted. Any cookie value of the page in a message comes back as [redacted].

With the Request details grant, start with details: true also keeps each request's request and response headers and bodies, each body cut at 1 MB. Cookie, Set-Cookie, Authorization and other headers whose names suggest a credential read [redacted], and so do credential-like fields (password, token, session and the like) of form and JSON bodies. requests and har page with after and next like the other reads, and return fewer entries when a reply would be too large. A tab holding a password you filled that didn't sign in refuses them with authenticationProtected.

Logs stay in Arx until the assistant reads them. They stop when the tab closes, and when you change or revoke the client's grant.

Sign-in

ToolNeedsWhat it does
browser_sign_insignInbegin, status or cancel a handoff on a tab and its exact origin. See Sign-ins stay with you.
browser_password_sign_insignInSigns in to a tab's exact origin with a password saved in the tab's profile, optionally in a same-site frameID. Returns only outcome (signedIn, needsUser or failed) and a reason. Arx asks you first unless you let agents sign in to that site without asking. See Signing in with a saved password.

Not available

There is no tool to read the clipboard, read or list saved passwords, reach the file system or attach a raw DevTools connection. Scripts run only in their own world, never the page's.