Tool reference

Every tool the Busymate MCP server exposes, grouped by what it does. There are 409 tools in total — a one-to-one mirror of the dashboard's read/write surface.

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.

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 (3)

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 (7)

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 (5)

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.

Entries (9)

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.

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 (16)

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. | set_breakpoint_patterns_global | Set the global breakpoint patterns per direction — requestPatterns (outbound) / responsePatterns (inbound); patterns is a legacy alias for the request direction. | global:edit | | set_breakpoint_patterns_device | Set a device's breakpoint patterns per direction — requestPatterns / responsePatterns; patterns is a legacy alias for the request direction. | devices:edit | | set_breakpoint_patterns_user | Set a USER's breakpoint patterns per direction (the middle tier global → user → device). Effective per device = global ++ user ++ device. | users:edit · confirm-gated | | set_breakpoint_patterns_service | Set a SERVICE GROUP's breakpoint patterns per direction (the SERVICE tier global → user → service → device); applies to every device that has applied the group. Effective per device = global ++ service ++ user ++ device. | services:edit · confirm-gated | | set_global_connection_type | Set the global default connection type. | global:edit | | set_user_connection_type | Set the per-user connection type. | users:edit | | set_my_display_name | Change YOUR OWN account display name (profiles.display_name for the calling account). Self-scoped — writes only the caller's own row (cannot name another user; '' clears it). | own-data (any signed-in user) | | get_my_account | YOUR account at a glance — one self-scoped read: profile (name/email/role/providers/user_id/created_at), per-user connection type (own + global default + effective), linked Telegram accounts, owned devices, subscription status, callable endpoints. Takes no target args — cannot read another user's account. | own-data (any signed-in user) | | delete_my_account | PERMANENTLY delete YOUR OWN account — the App Store 5.1.1(v) self-service deletion over MCP (profile + owned devices + captured traffic + API tokens + auth user). Self-only (no target args) + HUMAN-only (a device/service caller is refused). A protected reviewer/demo account is preserved ({ protected: true }). BusyBro-denylisted. | own-data · confirm-gated | | list_issue_reports | List issue reports from the one-tap reporter — your own by default, every reporter's with all:true (audit operators). Slim rows: title, status, occurrences, GitHub issue link, route + build. | own-data (audit:view for all:true) |

Control flows (3)

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

Pauses (2)

Block rules (5)

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 (6)

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 (7)

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

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 (4)

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 (7)

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 (4)

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

Total: 409 tools.