MCP Tool Reference

Here is everything the server exposes. Twenty-two tools, four groups. Read tools look; the rest act. Every call needs a valid key, and every result is scoped to that key's owner — admins aside, you only ever see your own devices and sessions.

Read tools

`list_devices`

Returns your fleet. Each device carries pad_id, device_name, device_group, platform, platforms, username, status, prompt_profile, and a computed busy flag with locked_by.

Use it to find valid pad_ids and to skip busy devices before you start a run.

`list_prompts(platform?, account?)`

Lists saved prompt templates, optionally filtered by platform (say tiktok) and by account (a pad_id). Returns id, name, platform, a task_preview, persona_id, brand_id, max_steps, usage_count, and any account-specific account_pad_ids.

`get_prompt(prompt_id)`

Returns one template in full: task, persona text, brand, LLM models, step limits, comment and search caps, capture settings, and account overrides.

`list_personas(account?)`

Lists saved personas with id, name, persona_text, account_pad_ids, and usage_count, optionally filtered by account.

`list_brands()`

Lists saved brands with id, name, aliases, and whether commenting guidelines exist.

`list_schedules(status?, run_type?)`

Lists scheduled runs. Admins see all; users see their own. Each row has id, name, run_type, status, schedule_type, timing_mode, timezone, next_run_at, last_run_at, run_count, and last_group_id. Filter by status or run_type (agentic_group | content_upload).

`get_schedule(schedule_id)`

Returns one schedule, including its full config, timing fields, max_runs_per_day, and Slack bot binding.

`list_sessions(limit?)`

Lists recent agentic sessions (engagement runs and content-run steps). Each row: group_id, user_id, managed_for_user_ids, task_preview, status, device_count, devices_succeeded, devices_failed, timestamps, and a session_link. limit defaults to 20, capped at 100.

`get_session_status(group_id)`

Tells you whether a session is running, completed, failed, or stopped, with per-device agent_statuses, failures, and a live flag. It reads live state when the run is in memory, and the stored record otherwise.

`list_content_runs(limit?)`

Lists recent multi-platform content runs with run_id, status, content_type, current_platform, and the platforms list. (experimental)

`get_content_run_status(run_id)`

Returns one content run's full status plus a session_link. (experimental)

Run tools

`start_run(...)`

Starts an agentic engagement run now. Pick exactly one driving mode:

Required: pad_ids. Optional overrides: llm_model, comment_llm_model, slack_bot_id, max_steps, return_home_on_finish, disable_proactive_search, capture_required, max_comments_per_session, max_searches_per_session.

Returns { group_id, session_link, task, pad_ids }. Devices are locked for the run; if one is busy, the call fails and names the holder.

`preview_run(pad_ids, engagement, platform?, prompt_id?)`

Resolves what each device would run, without starting anything. Call it to confirm per-device prompt and persona resolution before start_run.

`stop_run(group_id)`

Stops a running session across all devices. Admins, the run owner, and managed-for users may stop it.

Content tools *(experimental)*

`ingest_content(url? | drive_link?, filename?, content_base64?)`

Ingests media for a content run. url (alias drive_link) takes any direct public http(s) link — Google Drive "anyone with the link", Cloudflare R2, Supabase Storage, S3, Dropbox, presigned links. content_base64 takes raw bytes instead. Returns { files: [...] } with conbersa-file:// URIs to pass to start_content_run.

`start_content_run(groups, files, content_type?, ...)`

Starts a multi-platform content run. groups is a list of platform groups:

{
  "platform": "tiktok | facebook | instagram",
  "pad_ids": ["pad_1", "pad_2"],
  "caption": "optional per-platform caption",
  "sound_url": "optional TikTok sound link"
}

files is a list of { uri, original_name?, size? } from ingest_content. Media is pushed once; platforms run in sequence. Returns the run result plus a session_link.

`stop_content_run(run_id)`

Stops a multi-platform content run. The live platform stops; queued platforms are cancelled.

Schedule tools

`create_schedule(...)`

Creates a scheduled run. Common fields: name, pad_ids, run_type (agentic_group | content_upload), schedule_type (once | recurring), timing_mode (specific | random), timezone, scheduled_at, random_window_start, random_window_end, max_runs_per_day, max_steps, slack_bot_id.

• For agentic_group, pass prompt_id, task, or engagement.
• For content_upload, pass platform_groups, files, content_type, caption, sound_url.

`edit_schedule(schedule_id, ...)`

Updates only the fields you pass: name, status, schedule_type, timing_mode, timezone, scheduled_at, random window, max_runs_per_day, slack_bot_id, config.

`delete_schedule(schedule_id)`

Deletes a schedule.

`run_schedule_now(schedule_id)`

Fires a schedule immediately — the same path as the web app's Run now.

`stop_schedule(schedule_id)`

Stops the schedule's running session and re-arms or finishes the schedule.

Next

• MCP workflows — putting tools together.
• MCP troubleshooting — what the errors mean.