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
| Tool | Needs | Risk | What it does |
|---|---|---|---|
browser_inventory | read | read | Lists granted spaces, folders, pins, Favorites and tabs, with IDs and revisions. Never loads or focuses pages. |
browser_tabs | organize | mutate, destructive | Open, select, navigate, reload, go back or forward, stop, close, pin, unpin, move and favorite tabs. |
browser_folders | organize | mutate, destructive | Create, rename, move, ungroup and delete folders. |
browser_hosts | organize | mutate | Open Peek and Little Arx, and promote them to tabs. |
browser_spaces | browserAdmin to change, read to list | mutate, destructive | List, create, rename, re-theme, recolor, reorder, delete and show spaces. |
browser_profiles | browserAdmin to change, read to list | mutate, destructive | List, create, rename, recolor and delete profiles. |
browser_windows | read to list, organize to change | mutate | List windows, focus one, and open, swap or close Split View of up to four tabs. |
browser_archive | read to list, organize to restore | mutate | Search the Tab Archive and restore an entry. |
browser_history | history | read | Search visited pages. |
browser_downloads | downloads | mutate | List downloads, start one, cancel one, show one in Finder. |
browser_links | read | read | Clean a link, apply a Proxy Link rule, or resolve a bang. Nothing is opened. |
browser_batch | the classes of its steps | the highest of its steps | Up to 16 steps under one approval. |
browser_run | read, plus each step's own classes | each step's own | A 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 | |
|---|---|
action | The action name, from the list below. Spaces, profiles, windows, archive and downloads also take list. |
operationID | A fresh UUID for every change. Never retry after a disconnect. |
targetID, expectedRevision | The item to act on and its current inventory revision. |
destinationID, destinationRevision | Where a move, pin or restore goes. |
url, name, icon, theme | Per action. theme is light, dark or system. |
appearance, clearAppearance | For setSpaceAppearance and setProfileAppearance. See below. |
focus | true to bring the result forward. New tabs don't focus otherwise. Peek and Little Arx require it. |
| Tool | Actions |
|---|---|
browser_tabs | openTab, selectTab, navigate, reload, back, forward, stop, closeTab, pinTab, unpinTab, moveTab, addFavorite, removeFavorite, updateSavedURL, removeSavedEntry |
browser_folders | createFolder, renameFolder, moveFolder, ungroupFolder, deleteFolder |
browser_hosts | openPeek, openLittleArx, promotePeekToTab, promotePeekToLittleArx, promoteLittleArx |
browser_spaces | list, createSpace, renameSpace, setSpaceTheme, setSpaceAppearance, moveSpace, deleteSpace, selectSpace |
browser_profiles | list, createProfile, renameProfile, setProfileAppearance, deleteProfile |
browser_windows | list, openSplit, swapSplit, closeSplit, focusWindow |
Details that matter:
openTabalways 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 iscommittedwith that tab'stargetID, and the page isn't loaded again. See Tabs an assistant opens.openTabtargets a space and needsurl. Withroute: true, Air Traffic Control picks the destination:targetIDis then the source space, and the result'sroutereportsprofileID,spaceID,mode(mainBrowserorlittleArx),source(ruleorfallback) and the matched rule. The routed space must also be granted. No usable destination returnsrouteUnresolved.closeTabis destructive. Open tabs go to the Tab Archive; pins and Favorites keep their saved entry and only unload.moveTabinto a space of another profile reopens the URL there. The live session and cookies stay behind. Moving folders or Little Arx across profiles returnscrossProfileTransferUnsupported.removeSavedEntrydeletes a pin or Favorite. It's destructive, and Undo is in Arx.deleteFoldercloses everything inside, after each page allows it.ungroupFolderkeeps the children.openSplittargets a tab and shows it beside the current page. WithsplitTabs, 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.orientationishorizontal(side by side, the default) orvertical(stacked). Tabs leave any split they were in. A fifth tab, a Favorite as the target, or a window too small for the panes returnsinvalidRequest.swapSplitreverses the panes.openPeekneedssourceTabIDandsourceRevision, and previewsurlor, without one,targetID. Promotions takepresentationIDandpresentationRevisionfrom inventory.deleteSpacemoves the contents intodestinationIDwhen given, otherwise closes them. The last space can't be deleted.setSpaceAppearanceandsetProfileAppearancechange the window chrome's tint and film grain for one space or profile, the same way Settings does.appearanceis an object of the fields to choose:theme(lightordark),tintHue(0 to 360 degrees),tintIntensity(0 to 1),grainEnabled,grainIntensity(0 to 1),grainSize(1 to 3),accentColor(a preset such asredorteal, or#RRGGBB; see Accent color),matchesSite(trueorfalse: whether to match the site) andgradient("plain"for the tint's own, or{ "stops": [{ "hue": 30, "intensity": 0.5 }], "angle": 135 }with one or two more colors). A field set tonull(ortheme: "system") goes back to following the profile, or for a profile, Settings. Fields you leave out stay as they are.clearAppearance: trueclears the whole override first. Listed spaces and profiles show their ownappearanceand aresolvedAppearance, which is what their window actually shows.createProfile: a new profile isn't granted until you grant it.deleteProfileerases the profile's browsing data and needs a profile with no spaces left.- Results report
committedoracceptedLoading, 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.
browser_links
kind | Input | Returns |
|---|---|---|
clean | url | The link without tracking parameters. Sensitive parameters are kept. |
proxy | url | The link after your first matching Proxy Link rule. |
bang | query, such as !w swift | The 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 itsbrowser_prefix, such asclick({ ... }),read({ ... })orhistory({ ... }). A step returns the tool's result object; a failed step throws an error whosecodeis the tool's error code.- Every step is that tool call. It goes through the same grant, the same approval and its own
operationIDas 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 anoperationID,sleep(ms)waits up to 20 seconds,console.logprints, andkeepis 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
| Tool | Needs | What it does |
|---|---|---|
browser_wait | read | Waits up to 10 seconds (default 2) for the current page to stop loading. |
browser_inspect | pageContent | A semantic snapshot: text, roles, names and references you can act on. |
browser_read | pageContent | The page as Markdown or plain text. |
browser_find | pageContent | Finds text in a snapshot and returns references to it. |
browser_find_in_page | pageContent, interact | Chromium's find bar: highlights matches in the page. Risk: mutate. |
browser_pdf | pageContent | Exports the page to PDF, or reads the text of a PDF the tab shows. |
browser_capture | screenshots | A 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, expectedRevision | An ordinary HTTP(S) tab. |
limit | Nodes per page, 1 to 512, default 100. Pass nextCursor alone (as cursor) for the next page. |
load | true 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. |
frameID | Read a child frame, from an iframe node's frame. |
formValues | true adds values of eligible controls. Password, file, hidden, payment and one-time-code fields are always left out. |
bounds | true adds element bounds in viewport points, usable as a capture region. |
maximumTextBytes | Text 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 | |
|---|---|
mode | viewport, region, fullDocument or element |
region | { x, y, width, height } in viewport points, from the top left |
snapshotID, reference | For element, from a snapshot read with bounds: true |
scale | 0.1 to 1, default 1 |
format | png or jpeg; quality 0 to 1, default 0.8 |
offscreen | true captures a loaded background tab without showing it. Not for fullDocument. |
save | true 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.
| Tool | What it does |
|---|---|
browser_click | Activates a reference. With x/y, clickCount (1 to 3) or modifiers (shift, option, command), sends a real mouse click instead. |
browser_type | Focuses a field and types text (1 to 1,024 bytes) as real key events. A line feed presses Enter. Refuses password fields. |
browser_replace_text | Replaces a whole text field's value (up to 32,768 bytes). Not typing. |
browser_select_value | Picks one option by exact value, or several with values (up to 64) in a multiple select. |
browser_set_checked | Sets a checkbox or radio to checked true or false. |
browser_keypress | Presses one key, optionally with modifiers (shift, control, option, command). Browser and system shortcuts never run. |
browser_scroll | Scrolls the nearest scrollable container of a reference on one axis (horizontal, vertical) by deltaCSSPixels (−8,192 to 8,192). |
browser_hover | Moves the real pointer over a reference or point. Doesn't use up the snapshot. |
browser_drag | Drags from a reference or point to toReference or toX/toY, in steps (1 to 32, default 8). |
browser_upload | Answers 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_dialog | read the page's alert, confirm, prompt, before-unload dialog or permission request; accept (asks you every time) or dismiss it with its token. |
browser_media | list 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
| Tool | Needs | Risk | What it does |
|---|---|---|---|
browser_settings | browserAdmin | read, mutate, destructive | Reads 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:
section | What you get |
|---|---|
preferences | Each 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). |
routing | Your 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. |
searchShortcuts | Your search shortcuts (your own bangs). |
keyboardShortcuts | Every command's shortcut, and whether it's still the default. |
extensions | The extensions of profileID, and canInstall: whether installExtension is offered. Needs a whole-profile grant. |
sitePermissions | profileID'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. |
zoom | profileID'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.
action | Parameters |
|---|---|
setPreferences | values: 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. |
saveRoutingRule | rule: 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, setRoutingRuleEnabled | ruleID, plus offset (-1 earlier, 1 later) or enabled. Deleting is destructive. |
saveSearchShortcut | shortcut: keyword, name, template with {query}, and an optional homepage. replacing names the keyword it replaces. |
deleteSearchShortcut, setSearchShortcutEnabled | keyword, plus enabled. Deleting is destructive. |
setKeyboardShortcut | command and shortcut: { "key": "k", "modifiers": ["command", "shift"] }, or null to remove it. |
resetKeyboardShortcut | command. Restores its default. |
setExtensionEnabled | profileID, extensionID and enabled. |
installExtension | profileID 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. |
setSitePermission | profileID, 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. |
setSiteZoom | profileID, host (leave it out for the default) and factor, from 0.25 to 5, or null to remove the site's own zoom. |
undo | undoOperationID: 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:
access | What it means |
|---|---|
agent | The 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. |
user | Only 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. |
ui | Nothing 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 passesreplace: true, which takes it from that command, like Replace in Settings. A search keyword that's already taken is alsoshortcutConflict. - 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.
installExtensionwhen this Arx can't install from the Chrome Web Store (canInstallis 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 onlyaskorblock, oralloworblockfor pop-ups), or an origin that isn't anhttporhttpssite: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".
| Tool | Needs | Risk | What it does |
|---|---|---|---|
browser_evaluate | script | mutate, consequential | Runs JavaScript in the tab and returns what it returns, as JSON. A script that clicks, submits or sends always asks. |
browser_logs | devtools | read | Keeps 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.cookieis empty andcookieStoreisn'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)andnavigator.credentialsrefuse.- 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
action | What it does |
|---|---|
start | Starts keeping the tab's console messages and finished requests: up to 500 of each, newest kept. Nothing from before start is kept. |
console, network | Returns 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. |
requests | With 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. |
har | The same requests as a HAR 1.2 log. |
stop | Stops 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
| Tool | Needs | What it does |
|---|---|---|
browser_sign_in | signIn | begin, status or cancel a handoff on a tab and its exact origin. See Sign-ins stay with you. |
browser_password_sign_in | signIn | Signs 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.