FleetDeckDocs

MCP / Tool reference

fleetdeck_schedule

Schedule one autonomous task at an explicit ISO timestamp with timezone offset. A continuously running agent worker must claim it within 30 seconds. Use separate jobs for 09:00, 14:00 and 20:00; never guess the user's timezone.

Required permissionjobs:write + devices:control

Parameters

deviceIdstringrequired

Exact device ID from List devices. The current key must grant access to this phone.

min 1 charactersmax 128 characters
Example: "device_123"
Validation pattern^[A-Za-z0-9._:-]+$
namestringrequired

Name of the resource or operation. For commands with an enum, choose one of the listed values.

min 1 charactersmax 120 characters
Example: "Observe phone"
promptstringrequired

Task instructions passed to the external agent adapter. A worker must be running to execute them.

min 1 charactersmax 16,000 characters
Example: "Capture and describe the current screen without changing app state."
scheduledAtstringrequired

Future execution instant with an explicit UTC offset. Replace example timestamps with your intended schedule.

date-time
Example: "2030-01-01T11:00:00+01:00"
timezonestringrequired

IANA timezone metadata. scheduledAt remains the authoritative execution instant.

min 1 charactersmax 100 characters
Example: "Europe/Bratislava"
deadlineSecondsintegeroptional

Maximum job runtime in seconds; the worker stops the child at the finite deadline.

min 60max 3,600default 900
Example: 900

Unknown fields are rejected.

View JSON Schema
json
{
  "type": "object",
  "properties": {
    "deviceId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "pattern": "^[A-Za-z0-9._:-]+$"
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120
    },
    "prompt": {
      "type": "string",
      "minLength": 1,
      "maxLength": 16000
    },
    "scheduledAt": {
      "type": "string",
      "format": "date-time"
    },
    "timezone": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "deadlineSeconds": {
      "type": "integer",
      "minimum": 60,
      "maximum": 3600,
      "default": 900
    }
  },
  "required": [
    "deviceId",
    "name",
    "prompt",
    "scheduledAt",
    "timezone"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Call example

MCP call · SDK
const result = await client.callTool({
  name: "fleetdeck_schedule",
  arguments: {
    "deviceId": "device_123",
    "name": "Observe phone",
    "prompt": "Capture and describe the current screen without changing app state.",
    "scheduledAt": "2030-01-01T11:00:00+01:00",
    "timezone": "Europe/Bratislava",
    "deadlineSeconds": 900
  }
});
if (result.isError) {
  console.error(result.content);
} else {
  console.log(result.content);
}

The SDK example assumes an initialized MCP client. See connection setup for HTTP authentication, initialization and stdio configuration.

Response

The result contains content blocks and isError. The text block contains JSON with the fields below. See the corresponding REST response contract.

Illustrative tool result
{
  "content": [
    {
      "type": "text",
      "text": "{\n  \"id\": \"job_123\",\n  \"deviceId\": \"device_123\",\n  \"name\": \"Inspect phone\",\n  \"scheduledAt\": \"2030-01-01T10:00:00.000Z\",\n  \"timezone\": \"Europe/Bratislava\",\n  \"status\": \"queued\",\n  \"startedAt\": null,\n  \"finishedAt\": null,\n  \"cancelRequested\": false,\n  \"summary\": null\n}"
    }
  ],
  "isError": false
}
idstringalways present

Unique identifier of this resource. Use the returned value in subsequent requests.

min 1 charactersmax 128 characters
Validation pattern^[A-Za-z0-9._:-]+$
deviceIdstringalways present

Exact device ID from List devices. The current key must grant access to this phone.

min 1 charactersmax 128 characters
Validation pattern^[A-Za-z0-9._:-]+$
namestringalways present

Name of the resource or operation. For commands with an enum, choose one of the listed values.

scheduledAtstringalways present

Future execution instant with an explicit UTC offset. Replace example timestamps with your intended schedule.

date-time
timezonestringalways present

IANA timezone metadata. scheduledAt remains the authoritative execution instant.

statusstringalways present

Current state. A completed action means the driver finished; verify the intended screen or app effect separately.

Allowed:"queued""running""completed""failed""cancelled""missed""interrupted"
startedAtstring | nullalways present

UTC instant execution began, or null if it has not begun.

date-time
finishedAtstring | nullalways present

UTC instant execution ended, or null while no terminal outcome is recorded.

date-time
cancelRequestedbooleanalways present

Whether cancellation has been requested. Physical effects already delivered are not undone.

summarystring | nullalways present

Worker's completion summary. It describes the process outcome, not independently verified app success.

Behavior

  • The MCP descriptor marks this tool as potentially destructive and non-idempotent. The requestId protects action identity, not the external app effect.
  • FleetDeck handler errors return isError=true with a JSON text payload. SDK input validation may return plain-text error content, and authentication or transport can fail before a tool result exists. Screenshot results place image content in MCP image blocks and omit those bytes from the parallel JSON block.

Errors

401UNAUTHORIZEDMissing, malformed, expired or revoked credential; user verification/password state can also deny access.

Recovery: Use Authorization: Bearer with a valid scoped key. For dashboard routes, sign in. Job children require an active parent job and timely renewal.

Full error reference ↗
403FORBIDDENRequired scope, device grant, account membership or worker identity is missing.

Recovery: Check the endpoint’s scopes, exact device, owning key and workerId. A different key cannot access the original key’s sessions or jobs.

Full error reference ↗
404NOT_FOUNDUnknown route or resource unavailable to this caller.

Recovery: Check method/path and use returned IDs from this account/key. Do not guess IDs.

Full error reference ↗
402PLAN_REQUIREDDevice account has no active entitlement.

Recovery: Restore an active device entitlement in the workspace before controlling it.

Full error reference ↗
400INVALID_TIMESchedule is in the past or at/after a configured key expiry.

Recovery: Choose a future instant with the correct UTC offset, before key expiry if set. A no-expiry key has no key-expiry cutoff; job deadlines and leases still apply.

Full error reference ↗
409LIMITMaximum 50 active keys per user or 100 queued jobs per key.

Recovery: Revoke unused keys or cancel unnecessary queued jobs before creating more.

Full error reference ↗
422VALIDATIONA field, type, bound or unknown property failed validation.

Recovery: Read issues[].path and issues[].message. Match the endpoint schema; strict objects reject extra fields.

Full error reference ↗
Client onlyCONNECTION_FAILEDThe client could not reach the configured FleetDeck origin.

Recovery: Check DNS, TLS, proxy/firewall and FLEETDECK_BASE_URL. Before replaying a mutation, query its saved requestId when connectivity returns.

Full error reference ↗
Client onlyINVALID_RESPONSEThe server response was not valid FleetDeck JSON.

Recovery: Check that the base URL points to FleetDeck and that a proxy did not replace the response. Preserve the original action identifiers before retrying.

Full error reference ↗
500INTERNALUnexpected service error.

Recovery: Save nonsecret request context and time for support. Query action status before repeating a mutation; never assume it did not execute.

Full error reference ↗

SDK validation can return plain-text error content. Authentication and transport may fail before a tool result exists. Read the JSON-RPC and transport error reference before parsing the text as JSON.

Annotations

AnnotationValue
readOnlyHintfalse
destructiveHinttrue
idempotentHintfalse
openWorldHinttrue