Tool reference

Every tool the Busymate MCP server exposes, grouped by what it does. There are 188 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.

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

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:*.

Control flows (2)

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

Pauses (1)

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

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 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.

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

Legacy aliases (4)

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

Total: 188 tools.