Tool Reference

Tool List

Tool	Purpose	API usage
`health`	Return liveness status	None
`version`	Return MCP package version	None
`capabilities`	Return shared capability report model	None
`auth_login_start`	Create device code and verification URL	`POST /api/auth/device/start`
`auth_login_poll`	Poll device status and store tokens once authorized	`POST /api/auth/device/poll`
`auth_status`	Show local auth metadata	None
`auth_logout`	Revoke token and remove local auth state	`POST /api/auth/logout` (unless local-only)
`auth_whoami`	Resolve current authenticated profile	`GET /api/users/me` (+ `POST /api/auth/refresh` retry path)
`agents_list`	List agents for current user	`GET /api/agents`
`agents_get`	Get one agent by id	`GET /api/agents/:id`
`agents_create`	Create a new agent	`POST /api/agents`
`agents_update`	Update mutable agent fields	`PATCH /api/agents/:id`
`agents_delete`	Delete agent and teardown infra	`DELETE /api/agents/:id`
`agents_provision`	Provision a Fly machine for an agent	`POST /api/agents/:id/provision`
`agents_start`	Start an agent machine	`POST /api/agents/:id/start`
`agents_stop`	Stop an agent machine	`POST /api/agents/:id/stop`
`agents_status`	Read machine status for an agent	`GET /api/agents/:id/status`
`agents_clone`	Clone an agent into a new agent	`POST /api/agents/:id/clone`
`agents_runtime_update_status`	Get runtime update state for an agent	`GET /api/agents/:id/runtime-update-status`
`agents_runtime_update_grant`	Issue one-time runtime update grant	`POST /api/agents/:id/runtime-update-grant`
`agents_gateway_access`	Fetch gateway URL/token for an agent	`GET /api/agents/:id/gateway-access`
`agents_connect_telegram`	Connect Telegram channel for an online agent	`POST /api/agents/:id/connect-telegram`
`agents_whatsapp_qr`	Generate/retrieve WhatsApp QR login payload	`POST /api/agents/:id/whatsapp-qr`
`agents_whatsapp_wait`	Poll for WhatsApp login completion	`POST /api/agents/:id/whatsapp-wait`
`task_catalog`	List supported task action IDs for `task_run`	None
`task_run`	Execute mapped `users.`, `agents.`, `billing.` (including `billing.runtime-`), and runtime actions (`runtime.auth-status`, `runtime.agents.`, `runtime.updates.`, `runtime.delegations	delegation-create
`billing_status`	Return billing readiness + credits + entitlement snapshot	`GET /api/billing/summary`
`billing_summary`	Return raw billing summary payload	`GET /api/billing/summary`
`billing_usage_summary`	Return usage summary for a day range	`GET /api/billing/usage-summary`
`billing_checkout`	Create subscription checkout session	`POST /api/billing/checkout`
`billing_credits_checkout`	Create one-time credits checkout session	`POST /api/billing/credits/checkout`
`billing_portal`	Create billing portal URL	`POST /api/billing/portal`
`billing_sync`	Trigger billing sync	`POST /api/billing/sync`
`billing_setup`	Checkout when plan is provided; otherwise portal for active subscriptions	`POST /api/billing/checkout` or `POST /api/billing/portal`
`billing_runtime_requests_list`	List runtime spend approval requests	`GET /api/billing/runtime-requests`
`billing_runtime_request_get`	Fetch one runtime spend request	`GET /api/billing/runtime-requests/:id`
`billing_runtime_request_approve`	Approve and execute runtime spend request	`POST /api/billing/runtime-requests/:id/approve`
`billing_runtime_request_deny`	Deny runtime spend request	`POST /api/billing/runtime-requests/:id/deny`
`billing_runtime_spend_policy_get`	Get runtime spend policy for controller agent	`GET /api/billing/runtime-spend-policies/:controllerAgentId`
`billing_runtime_spend_policy_set`	Create/update runtime spend policy	`POST /api/billing/runtime-spend-policies/:controllerAgentId`
`billing_runtime_spend_policy_revoke`	Revoke runtime spend policy	`DELETE /api/billing/runtime-spend-policies/:controllerAgentId`
`runtime_delegations_list`	List runtime delegation grants	`GET /api/runtime/delegations`
`runtime_delegation_create`	Create runtime delegation grant	`POST /api/runtime/delegations`
`runtime_delegation_revoke`	Revoke runtime delegation grant	`DELETE /api/runtime/delegations/:id`
`runtime_auth_status`	Read runtime auth status for current runtime principal	`GET /api/runtime/auth/status`
`runtime_updates_manifest`	Read runtime update manifest metadata	`GET /api/runtime/updates/manifest`
`runtime_updates_check`	Check runtime update availability/target for current runtime	`POST /api/runtime/updates/check`
`runtime_updates_apply`	Apply runtime update decision with grant token	`POST /api/runtime/updates/apply`
`runtime_updates_report`	Report runtime version after update execution	`POST /api/runtime/updates/report`
`runtime_agents_start`	Start runtime-target agent machine using runtime auth	`POST /api/runtime/agents/:id/start`
`runtime_agents_stop`	Stop runtime-target agent machine using runtime auth	`POST /api/runtime/agents/:id/stop`
`runtime_agents_status`	Read runtime-target agent machine status using runtime auth	`GET /api/runtime/agents/:id/status`

Inputs

Auth Tools

auth_login_start

controlPlaneUrl?: string
clientName?: string

auth_login_poll

deviceCode: string
controlPlaneUrl?: string
storePath?: string

auth_status

storePath?: string

auth_logout

controlPlaneUrl?: string
storePath?: string
localOnly?: boolean

auth_whoami

controlPlaneUrl?: string
storePath?: string

Agent Lifecycle Tools

agents_list

controlPlaneUrl?: string
storePath?: string

agents_get

id: string
controlPlaneUrl?: string
storePath?: string

agents_create

name: string
persona?: string
avatar?: string
plan?: string
channels?: object
capabilities?: object
controlPlaneUrl?: string
storePath?: string

agents_update

id: string
name?: string
persona?: string
avatar?: string
channels?: object
capabilities?: object
controlPlaneUrl?: string
storePath?: string

agents_delete

id: string
controlPlaneUrl?: string
storePath?: string

agents_provision

id: string
controlPlaneUrl?: string
storePath?: string

agents_start

id: string
controlPlaneUrl?: string
storePath?: string

agents_stop

id: string
controlPlaneUrl?: string
storePath?: string

agents_status

id: string
controlPlaneUrl?: string
storePath?: string

agents_clone

id: string
name?: string
controlPlaneUrl?: string
storePath?: string

agents_runtime_update_status

id: string
currentVersion?: string
channel?: string
controlPlaneUrl?: string
storePath?: string

agents_runtime_update_grant

id: string
currentVersion?: string
channel?: string
targetVersion?: string
controlPlaneUrl?: string
storePath?: string

agents_gateway_access

id: string
controlPlaneUrl?: string
storePath?: string

agents_connect_telegram

id: string
controlPlaneUrl?: string
storePath?: string

agents_whatsapp_qr

id: string
controlPlaneUrl?: string
storePath?: string

agents_whatsapp_wait

id: string
controlPlaneUrl?: string
storePath?: string

Action Dispatch Tools

task_catalog

No inputs.

task_run

action: string
input?: object
controlPlaneUrl?: string
storePath?: string
For runtime actions (runtime.auth-status, runtime.agents.start, runtime.agents.stop, runtime.agents.status, runtime.updates.manifest, runtime.updates.check, runtime.updates.apply, runtime.updates.report), provide runtime auth args in input:
- input.runtimeStorePath?: string
- input.controlPlaneUrl?: string
- input.id?: string (for runtime.agents.*; defaults to local runtime agent when omitted)
- input.currentVersion?: string (for runtime.updates.check|apply)
- input.channel?: string (for runtime.updates.check|apply)
- input.targetVersion?: string (for runtime.updates.check|apply)
- input.grantToken: string (required for runtime.updates.apply)
- input.version: string (required for runtime.updates.report)

Examples:

{
  "action": "runtime.updates.apply",
  "input": {
    "runtimeStorePath": "/data/.roberto/runtime-auth.json",
    "controlPlaneUrl": "https://api.roberto.example",
    "grantToken": "rug_123",
    "currentVersion": "2026.02.20",
    "channel": "stable"
  }
}

{
  "action": "billing.runtime-policy-set",
  "input": {
    "controllerAgentId": "agent_controller_1",
    "maxSingleUnits": 100,
    "maxDailyUnits": 1000,
    "maxMonthlyUnits": 5000,
    "enabled": true,
    "expiresAt": "2026-03-31T00:00:00.000Z"
  }
}

Billing Tools

billing_status

controlPlaneUrl?: string
storePath?: string

billing_summary

controlPlaneUrl?: string
storePath?: string

billing_usage_summary

days?: number (bounded to 7..365)
controlPlaneUrl?: string
storePath?: string

billing_checkout

planCode: "starter" | "pro" | "team"
controlPlaneUrl?: string
storePath?: string

billing_credits_checkout

packageCode: "credits_3000" | "credits_6000" | "credits_12000"
controlPlaneUrl?: string
storePath?: string

billing_portal

controlPlaneUrl?: string
storePath?: string

billing_sync

controlPlaneUrl?: string
storePath?: string

billing_setup

planCode?: "starter" | "pro" | "team"
controlPlaneUrl?: string
storePath?: string

billing_runtime_requests_list

status?: "pending" | "approved" | "denied" | "executed" | "expired"
limit?: number (bounded to 1..100)
controlPlaneUrl?: string
storePath?: string

billing_runtime_request_get

id: string
controlPlaneUrl?: string
storePath?: string

billing_runtime_request_approve

id: string
controlPlaneUrl?: string
storePath?: string

billing_runtime_request_deny

id: string
controlPlaneUrl?: string
storePath?: string

billing_runtime_spend_policy_get

controllerAgentId: string
controlPlaneUrl?: string
storePath?: string

billing_runtime_spend_policy_set

controllerAgentId: string
maxSingleUnits: number
maxDailyUnits: number
maxMonthlyUnits: number
enabled?: boolean
expiresAt?: string (ISO datetime)
controlPlaneUrl?: string
storePath?: string

billing_runtime_spend_policy_revoke

controllerAgentId: string
controlPlaneUrl?: string
storePath?: string

runtime_delegations_list

runtimeId?: string
activeOnly?: boolean
limit?: number (bounded to 1..100)
controlPlaneUrl?: string
storePath?: string

runtime_delegation_create

runtimeId: string
scope?: object
ttlSeconds?: number
expiresAt?: string (ISO datetime)
controlPlaneUrl?: string
storePath?: string

runtime_delegation_revoke

id: string
controlPlaneUrl?: string
storePath?: string

runtime_auth_status

controlPlaneUrl?: string
runtimeStorePath?: string (defaults to ROBERTO_RUNTIME_AUTH_STORE_PATH or /data/.roberto/runtime-auth.json)

runtime_updates_manifest

controlPlaneUrl?: string
runtimeStorePath?: string (defaults to ROBERTO_RUNTIME_AUTH_STORE_PATH or /data/.roberto/runtime-auth.json)

runtime_updates_check

currentVersion?: string
channel?: string
targetVersion?: string
controlPlaneUrl?: string
runtimeStorePath?: string (defaults to ROBERTO_RUNTIME_AUTH_STORE_PATH or /data/.roberto/runtime-auth.json)

runtime_updates_apply

grantToken: string
currentVersion?: string
channel?: string
targetVersion?: string
controlPlaneUrl?: string
runtimeStorePath?: string (defaults to ROBERTO_RUNTIME_AUTH_STORE_PATH or /data/.roberto/runtime-auth.json)

runtime_updates_report

version: string
controlPlaneUrl?: string
runtimeStorePath?: string (defaults to ROBERTO_RUNTIME_AUTH_STORE_PATH or /data/.roberto/runtime-auth.json)

runtime_agents_start

id?: string (defaults to local runtime agent from runtime auth store)
controlPlaneUrl?: string
runtimeStorePath?: string (defaults to ROBERTO_RUNTIME_AUTH_STORE_PATH or /data/.roberto/runtime-auth.json)

runtime_agents_stop

id?: string (defaults to local runtime agent from runtime auth store)
controlPlaneUrl?: string
runtimeStorePath?: string (defaults to ROBERTO_RUNTIME_AUTH_STORE_PATH or /data/.roberto/runtime-auth.json)

runtime_agents_status

id?: string (defaults to local runtime agent from runtime auth store)
controlPlaneUrl?: string
runtimeStorePath?: string (defaults to ROBERTO_RUNTIME_AUTH_STORE_PATH or /data/.roberto/runtime-auth.json)

Response Patterns

Tools return text content containing JSON payloads.
Authenticated tools read persisted auth state and retry one refresh cycle on 401 where applicable.
Validation errors are surfaced as MCP tool errors with a descriptive message.