Tool reference

The Busymate MCP server exposes 454 tools — a one-to-one mirror of the dashboard's read/write surface. This page groups and explains them by what they do.

Every served tool is on this page. The named families below are written by hand — they carry the reasoning a generator cannot — and the rest are projected from the same tool registry the server runs, so the two sets together are exactly the roster mcp.busymate.dev serves. A tool added to the product without a row here cannot land.

The authority on arguments is still the server's own tools/list. Each row is one line; the full description and JSON schema come back from tools/list over any transport. Busymate AI's own management tools are not here — they serve only on busymate.ai/mcp.

How to read this page

Each tool carries permission gating, enforced server-side on every call:

• section:view / section:edit — a capability check against your RBAC role. You need the named capability (e.g. devices:edit) for the call to run. Built-in admin grants all; built-in viewer is read-only.
• confirm-gated — a destructive action that requires an explicit confirm: true (or confirm: "all") argument. The agent must opt in deliberately; a stray call is rejected.
• admin-only — restricted to admin roles regardless of capabilities.
• owner-scoped — no capability needed; the tool only ever reads or writes the caller's own row.
• per-table — the generic CRUD tools resolve the capability from the table they touch.

Tools are scoped to your account and RLS — you only ever see and touch your own devices, entries, and settings.

Generic CRUD — db_* (5)

Low-level PostgREST access to allowlisted tables. The section gate is per-table: each table maps to a capability section, and db_select/db_rpc need view, the mutators need edit. Update and delete reject empty filters.

Realtime & introspection (2)

Device reads (4)

Device realtime control (8)

Control flows delivered over Realtime to a paired device. The destructive ones are confirm-gated.

External / upstream proxy control (2)

Route a device's egress through an upstream proxy so its public IP and country become the proxy's.

Remote browser / CDP control (9)

Drive a real Chrome that a bmc (cdp-connector) device controls. Every command needs the per-device remote-control opt-in to be ON; the raw escape hatch is admin-only.

Named CDP device daemon (7)

Lifecycle of named CDP "devices" (Chrome instances on a bmc machine), plus hot-updating the daemon itself. The mutators are confirm-gated.

Custom browser profiles (4)

CRUD over the browser_profiles table of custom Chromium-family launch profiles authored in the dashboard (Settings → CDP) and synced to the bmc CLI. The five built-ins (chrome / brave / edge / godbrowser / chromium) live in the CLI code — they're reserved slugs and never appear here.

Android farm (28)

The Android farm (#148) pairs one HOST device per Mac Mini (platform: android-host) and models each connected phone as its own UUID-keyed child android device row, parented to the host (parent_device_id). The Edge function can't run ADB, so every farm control tool dispatches a farm-command to the host over its private device:<uuid> Realtime channel and awaits farm-result — the same host-routed pattern as the CDP daemon tools, gated by the host's cdpControlEnabled opt-in. Identify the host with device_uuid/deviceName; target specific phones with child_uuid/child_uuids (the route-key uuid, never the volatile ADB serial), or omit to target all online phones. The raw executors carry arbitrary device control (browser_cdp-tier) — they're admin-gated, iOS-refused, and never offered to the BusyBro chat LLM.

Farm fleet components (4)

The per-component lifecycle behind the dashboard Phone Farm → Info tab. A farm device (a host or a phone) reports every driver that makes it controllable — the DevTools app, the DeviceKit runner, the broadcast mirror, the developer disk image, the CA trust, WebDriverAgent, and the host's own go-ios / mobile-mcp / scrcpy / adb / farm-daemon — each with an honest state (absent / outdated / current / unknown). These four tools act on that surface. device_uuid / deviceName selects the host to route to; child_uuid (a phone's route-key uuid) selects the target device, or omit it for the host's own component. Each streams step-by-step farm-action-progress events on the host's device:<host-uuid> channel and returns a run_id to correlate them.

The daemon reports honest evidence — the new installed version on a successful install/update/reinstall, the fresh probe outcome on a recheck, or an explicit refusal for a non-updatable or unknown component (never a false success).

Ad-hoc proof install — farm_component_action extra arguments

Three optional arguments turn farm_component_action into the remote pre-TestFlight proof install. They apply to the devtools-app component on an iPhone only and are refused (never silently ignored) anywhere else — including on an Android phone, where an adb install of the published APK has no code-signing mode.

Switching modes uninstalls the old build first in either direction — iOS refuses an in-place cross-signer replace, so the app's data is reset. On iOS 26 a sideloaded build needs a one-time online verification at first launch, so the phone must have internet; installed-but-not-launched is reported honestly as launch-unverified, never as success. See the farm architecture for the full pipeline.

Farm app sign-in (1)

An installed app is not a proof-ready app: both apps open on a sign-in gate, and a screenshot of a gate proves nothing about the feature being shipped. This is what gets past it without a person at the rack.

identity picks the mechanism, and the two arms are different in kind:

Two properties worth relying on: it never guesses — a credential that input text cannot reproduce verbatim is refused rather than typed, because a silently altered password is indistinguishable from a wrong one, and a gate left with text in it from an interrupted attempt gets one force-stop and a retry rather than a blind submit. And app is a symbolic name ("devtools"), never a package id, because this path types a real password into whatever is on screen and may only ever drive an app we ship.

The reply is a three-field allowlist — { ok, status, signedInAs, device } — so nothing credential-shaped can travel back. Omitting identity sends no identity argument at all, keeping the payload byte-identical to a call made before the arm existed. The dashboard mirror is the /farm Info tab's App sign-in card; see the pre-TestFlight proof install.

Entries (12)

Read, tag, search, and inspect captured request / response pairs. summarize_device_traffic is the one to reach for first on a busy device — a bounded, index-only profile of which hosts/endpoints dominate, without scanning raw rows. inspect_requests is the deep one — full headers and bodies for reverse-engineering an API. delete_entries is the precise, targeted counterpart to the whole-device wipe_entries.

inspect_requests and export_har return real captured headers and bodies — treat any tokens, cookies, or credentials in them as secrets.

Observed API (13)

Evidence-backed API discovery over traffic visible to the caller. The immutable observation graph is the stored truth; OpenAPI 3.1 is a deterministic, secret-safe projection. All thirteen tools are owner-scoped through user-token RLS and are available to BusyBro from the same canonical registry. Every writer is confirm-gated. (The former publish_api_artifact — Observed-API revision → self-contained artifact — was removed from the DevTools MCP under #1985 La, since artifacts are Busymate AI only.)

Service groups (5)

A service group can link one or more BusyBro specialist agents from the busybro_agents registry, with exactly one primary (the service's lens + default run_task target) and an explicit order. list_service_groups / get_service_group return each group's primary_agent plus its ordered agents[].

The legacy service_groups.ai_agent jsonb (the old single inline {enabled, name, instructions} per-service agent) and the deprecated service_groups.agent_id FK have been dropped — link agents with set_service_group_agents instead (the service_group_agents join is the single source of truth). upsert_service_group still accepts an ai_agent arg for back-compat but ignores it.

Tags (3)

Settings & environment (20)

Effective settings (global / per-user / per-service / per-device), environment variables, connection types, and breakpoint patterns. Env values are masked on read and never echoed on write; reference them later as {{KEY}} in resend_request and browser_eval. The env tools gate dynamically by scope — global checks global:*, device checks devices:*.

#965 — one tool per scope. These were once four tools taking a scope: 'global'|'device' argument. That shape could not be owner-scoped: an ownership tag authorizes the caller against an owned device, but the handler picked its resource from scope, so {scope:'global', device_uuid:<a device you own>} would have passed the ownership check and been served the ownerless settings_global singleton. Splitting per scope makes the gate and the dispatch agree by construction — each tool addresses exactly one store.

Control flows (3)

Realtime control directed at the proxy-server / device handling a paused request.

Pauses (2)

Block rules (6)

Auto-block requests matching a method + host/path wildcard, before they reach upstream. The rule action is one of three variants: block returns a synthetic error response (status default 403, body, contentType); drop tears the connection down; mock returns a synthetic SUCCESS response (status default 200, optional string→string headers map, body, contentType). Stored in settings_{global,device}.data.blockRules; effective per device = global ++ device (de-duped by id).

Each rule also accepts an optional maxRuns integer — a run-count cap. Omit it (or pass a non-positive value) for unlimited (the default); maxRuns: 1 makes the rule fire once then auto-disable. The cap is set at creation right here on the rule object and applies to any action type. The count is tracked per device and persisted (it survives reconnect/restart — "once ever"), and a global rule that hits its cap is suppressed only on the device that reached it, never fleet-wide. See Block rules for the full semantics.

Example mock rule (force a JSON 200):

{ "id": "33333333-3333-3333-3333-333333333333", "enabled": true, "method": "GET",
  "pattern": "api.doordash.com/v3/feature_flags",
  "action": { "type": "mock", "status": 200, "headers": { "x-mocked-by": "busymate" },
    "contentType": "application/json", "body": "{\"flags\":{\"new_ui\":true}}" } }

Example one-shot mock rule (maxRuns: 1 — fire a single synthetic 401 to force a token refresh, then auto-disable):

{ "id": "44444444-4444-4444-4444-444444444444", "enabled": true, "method": "GET",
  "pattern": "api.example.com/v1/me",
  "action": { "type": "mock", "status": 401, "contentType": "application/json",
    "body": "{\"error\":\"token_expired\"}" },
  "maxRuns": 1 }

Scripting engine (7)

Scripts are sandboxed JavaScript hooks (onRequest / onResponse) the proxy-server, cdp-connector, and iOS VPN run inline to mutate or synthesize matching requests/responses — the grown-up evolution of a Mock block rule. They live in settings_{global,user,device}.data.scripts; effective per device = global ++ user ++ device (de-duped by id, device wins then user then global), the same model as block rules. Writing a script is arbitrary-code power (browser_cdp-tier): the write tools need scripts:edit + admin + confirm: true at EVERY tier (the user tier does not lower the bar), enforced at the database layer (settings_{global,user,device}_scripts_gate) so no surface can smuggle a script in via a blocks write or a self-write.

A script object is { id, enabled, name, pattern, method?, phase: "request" | "response" | "both", code, version?, note? }.

Workspaces (6)

Tabs (6)

Snapshots (3)

Push (2)

Roles & RBAC (8)

Manage capability-based roles. All mutators are confirm-gated.

Demo program admin (6)

The demo-account lifecycle (mint → reset → regenerate → delete). Every mutator is admin-only + confirm-gated and re-asserts admin in-handler; everything is inert while the demo kill-switch is off.

Tenancy & white-label — served elsewhere

The white-label tenancy tools are not on this server. set_tenant_branding, add_tenant_admin, rename_tenant_slug, set_tenant_slug_aliases, set_tenant_domain and the rest of the tenant lifecycle are Busymate AI management tools, served only at busymate.ai/mcp. The separation is enforced in code, not by convention: a DevTools host refuses them as unknown tools, and a Busymate AI host refuses the DevTools surface the same way. This page listed two of them until docs 233; a call to either against mcp.busymate.dev was always rejected.

Busymate AI's own profile is a separate, larger surface, documented with that product.

Stats & status (2)

Tester (2)

The architecture-prove verdict board — read the latest test run + trigger a new one.

Telegram linking (5)

Link a Busymate account to a Telegram identity for BusyBro chat.

TestFlight beta admin (13)

Manage TestFlight groups, testers, and invitations via the testflight-admin Edge Function. Reads need testflight:view; every write needs testflight:edit and is confirm-gated.

BusyBro memory & shares (5)

BusyBro's long-term memory and shared-conversation reader. The memory trio is owner-scoped — you only ever see and touch your own account's memories, the same store the dashboard and Telegram BusyBro read and write.

BusyBro sessions (5)

Multi-session chat management — a "session" is one busybro_threads row (a resumable conversation), shared across the dashboard, iOS, and the bmc CLI. All five are owner-scoped — you only ever list / load / rename / delete your own sessions. context_key is the dashboard nav-binding find-or-create key (UUID-keyed, e.g. device:<uuid>); last_active_at is the sidebar ordering anchor.

BusyBro attachments (1)

The read leg of the BusyBro attachments program (files / photos / videos uploaded to BusyBro chats — the durable rows in public.busybro_attachments, bytes in the private busybro-attachments bucket). Owner-scoped — you only ever see your own uploads, and there is no fleet arm.

BusyBro global (team) memory governance (10)

The shared, non-personal team-knowledge store and its review queue — see Global (team) memory and the shareable Connect to team memory page. The shared store has no user_id and is leak-proof on the recall path; contributor identity surfaces only through list_memory_contributors, never in what an LLM recalls. Proposals land pending (not recallable) until an operator approves them.

The recall store (busybro_global_memories) carries no identity — match_global_memories returns no user_id. Per-person provenance lives only in the busybro_global_contributions side-table, read only by list_memory_contributors (operator-gated), for dedup, corroboration, stats, and erasure — never on the recall path. The dashboard review queue shows a candidate's contributor count, never identities.

External MCP servers & personal connectors (13)

BusyBro consumes other MCP servers as a client — a GLOBAL, admin-managed registry (busybro_mcp_servers, rows with owner_user_id IS NULL) plus personal connectors (#830): the same table with owner_user_id set, self-service for any signed-in user, owner-scoped end-to-end. Credentials are value-blind everywhere — a Bearer token is written to Vault and never read back; an OAuth connector's tokens (#899) are acquired by the server-side consent flow and never pass through any tool argument or response.

An OAuth connector's access / refresh tokens live only in Vault under server-derived names — no tool, REST read, or log ever returns one. A dead grant (revoked / expired refresh) flips the connector to needs_reauth and BusyBro says so honestly at turn start ("needs to be reconnected") instead of silently advertising zero tools.

Stripe billing & admin (9)

Subscription + metered (captured_entries) billing (Phase 1 = Stripe TEST mode). The owner-scoped reads filter on the caller's identity; operators pass all_users:true for the fleet. The admin reads back the /billing-admin operator surface — all value-blind (get_stripe_config derives test/live mode from the publishable-key prefix and NEVER returns the secret key or webhook signing secret).

Directory catalogue (9)

The BusyBro Directory — the operator-curated catalogue that merchandises skills, connectors, and plugins to the consumer BusyBro app. ONE model (busybro_directory_listings) backs all three collections; the item tables stay about function, the listing owns presentation. install_count is real installs only (RPC-incremented, never operator-editable — a fresh catalogue renders no counts); the Community and New badges derive from author_kind / published_at, so the stored badge taxonomy is exactly {verified, trending}.

Legacy aliases (2)

Older names kept for backward compatibility. Prefer the generic db_* tools or the typed reads / writes above for new work.

Removed, not renamed. The blanket settings patchers get_settings, set_global_settings, set_device_settings and clear_device_settings were listed here until docs 233 and no longer exist on any host. Each was replaced by a first-class tool that writes exactly one thing without clobbering its neighbours — get_global_settings / get_device_settings to read, and set_inspect_all_requests, set_mitm_all_hosts, set_device_capture_enabled, set_device_autostart, the set_block_rules_* / set_breakpoint_patterns_* / set_scripts_* families and the per-scope env tools to write. A call to an old name is rejected as an unknown tool.

Total: 454 tools.

Every other tool — generated from the registry

The families above are written by hand and do not cover the whole surface. The other 203 are listed here, projected from the same tool registry the server itself dispatches from — its own name, opening line and permission gating — so this page cannot fall behind the product. A tool added to the surface without a row here fails the build.

Each cell is the tool's own opening line. The full text, arguments and JSON schema are what tools/list returns — ask the server when you need the exact contract.

Busymate AI's management tools are deliberately absent. They serve only on busymate.ai/mcp; a call to one against mcp.busymate.dev is rejected (STRICT NO-MIX).

Devices (22)

Settings (7)

Push (APNs) (1)

Roles & capabilities (7)

Audit trail (2)

Advisor Center (5)

TestFlight (1)

Scripting engine (2)

Remote browser control (2)

Android farm (45)

iOS farm (15)

App secrets (Vault) (4)

Stripe admin (4)

BusyBro settings (2)

BusyBro usage & cost (1)

To-dos (6)

Notifications (7)

BusyBro agents (4)

BusyBro skills (14)

BusyBro memory imports (4)

Tester (6)

WIP board (4)

Account (4)

Plugins (7)

Federation clients (3)

MCP servers (1)

Localization (i18n) (23)