MCP / Tool reference
fleetdeck_text
Run text on the selected session. Inspect the screen to verify effects.
Parameters
sessionIdstringrequiredSession ID returned by Acquire a session. Use the key that owns that session.
"session_123"Validation pattern
^[A-Za-z0-9._:-]+$requestIdany JSONrequiredYour stable action identifier, unique within the session. Reusing it with the same command retrieves the existing action; changing the command causes IDEMPOTENCY_CONFLICT.
"text-001"valuestringrequiredText to type or write; for a clipboard read, the returned plaintext value. Writing the clipboard does not paste it.
"Hello from FleetDeck"Unknown fields are rejected.
View JSON Schema
{
"type": "object",
"properties": {
"sessionId": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$"
},
"requestId": {
"$ref": "#/properties/sessionId"
},
"value": {
"type": "string",
"maxLength": 16000
}
},
"required": [
"sessionId",
"requestId",
"value"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}Call example
const result = await client.callTool({
name: "fleetdeck_text",
arguments: {
"sessionId": "session_123",
"requestId": "text-001",
"value": "Hello from FleetDeck"
}
});
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.
{
"content": [
{
"type": "text",
"text": "{\n \"id\": \"action_123\",\n \"requestId\": \"text-001\",\n \"status\": \"completed\",\n \"kind\": \"text\",\n \"createdAt\": \"2030-01-01T10:00:00.000Z\",\n \"finishedAt\": \"2030-01-01T10:00:00.000Z\",\n \"result\": {\n \"status\": \"submitted\",\n \"verified\": false,\n \"instruction\": \"Take a fresh screenshot to verify the intended effect\"\n }\n}"
}
],
"isError": false
}Action tools return an ActionRecord. Screenshot bytes appear in separate MCP image blocks and are removed from the text block’s result.content. Native results vary by driver. Failed, unknown and cancelled actions set isError to true; queued or running actions still require a status check.
idstringalways presentUnique identifier of this resource. Use the returned value in subsequent requests.
Validation pattern
^[A-Za-z0-9._:-]+$requestIdstringalways presentYour stable action identifier, unique within the session. Reusing it with the same command retrieves the existing action; changing the command causes IDEMPOTENCY_CONFLICT.
Validation pattern
^[A-Za-z0-9._:-]+$statusstringalways presentCurrent state. A completed action means the driver finished; verify the intended screen or app effect separately.
"queued""running""completed""failed""unknown""cancelled"kindstringalways presentAction type that produced this record.
"screenshot""inspect""apps""tap""double_tap""long_press""swipe""text""key""button""open_url""launch_app""kill_app""clipboard_get""set_clipboard""push_media""media_chunk""native_tool"createdAtstringalways presentUTC instant when the record was created.
finishedAtstring | nullalways presentUTC instant execution ended, or null while no terminal outcome is recorded.
resultany JSON | nullalways presentDriver-defined JSON or null. Known shapes are documented in ActionResult; native tool output may differ.
View child fields
statusstringoptionalCurrent state. A completed action means the driver finished; verify the intended screen or app effect separately.
"submitted""applied""staged""imported"verifiedbooleanoptionalMedia import acknowledgement is not publication verification. Other input normally returns false.
instructionstringoptionalDriver guidance for the next observation or recovery step.
contentobject[]optionalContent blocks returned by the driver. Screenshot image blocks contain base64 image bytes.
View child fields
typestringalways presentDiscriminator that selects the action or content shape.
"image"mimeTypestringalways presentMIME type of the returned image.
"image/jpeg""image/png"datastringalways presentBase64 image bytes, without a data URL prefix.
widthintegeroptionalCaptured image width in pixels.
heightintegeroptionalCaptured image height in pixels.
capturedAtstringoptionalUTC capture timestamp supplied by the relay.
coordinateSpacestringoptionalCoordinate convention for common FleetDeck actions. Normalized x/y values are relative to the current screen.
xmlstringoptionalADB UI hierarchy XML; bounds use screen pixels.
treeany JSONoptionalWDA accessibility tree; shape varies by version.
screenobjectoptionalADB {w,h} pixels; WDA {width,height} logical points.
packagesstring[]optionalAndroid package-name strings returned by ADB app inventory.
appsany JSON[]optionalPhone-agent-defined app entries. Entry fields depend on the agent version.
valuestringoptionalPlaintext clipboard value.
codestringoptionalExecution error code, distinct from an HTTP error.
errorstringoptionalHuman-readable failure explanation. Use code for programmatic handling.
Behavior
Type into the focused control. value allows up to 16,000 characters, including empty text. ADB input supports ASCII only and rejects literal %s; use a compatible relay/IME or native tool for other text.
- This convenience tool creates the same action record as fleetdeck_action and waits with session keepalive. Use a stable requestId for recovery.
- 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 ↗409SESSION_EXPIREDSession expired, was closed or belongs to another key.
Recovery: Read the original action if needed, acquire a new session and inspect before new input. Heartbeat before the returned expiresAt; temporary child keys can have much shorter sessions than 120 seconds.
Full error reference ↗409ACTION_BUSYThis session has queued or running work.
Recovery: Poll the existing action to a terminal state before issuing another.
Full error reference ↗409IDEMPOTENCY_CONFLICTrequestId already identifies a different command.
Recovery: Retrieve that original action. Reuse its exact command only for lookup/retry; use a new ID only for a newly intended action.
Full error reference ↗429RATE_LIMITAt most 120 new actions per session in a rolling minute.
Recovery: Pause until the window clears. Poll existing actions instead of resubmitting new work. No Retry-After header is currently supplied.
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 ↗Driver execution errors
Action result (driver 422)UNSUPPORTEDTool or parameter is unavailable on this transport, OS or phone-agent version.
Recovery: Recheck capabilities and driver limitations. Connect a suitable private native bridge or update the phone agent; verify actual hardware support.
Full error reference ↗Native driver 422UNSUPPORTED_TEXTADB input cannot encode the requested text.
Recovery: Use ASCII without literal %s, or a compatible relay/IME/native extension. The bridge stores UNSUPPORTED_TEXT as failed with its code; inspect the action result.
Full error reference ↗Action result (driver 422)MEDIA_IMPORT_FAILEDPhone rejected Photos/gallery import.
Recovery: Check complete file bytes, MIME, supported agent version and Photos/gallery permission. Inspect the gallery before retrying.
Full error reference ↗Action result (driver 502/503/504)DEVICE_UNAVAILABLEPhone or relay could not provide the requested operation.
Recovery: Check online state, capture/USB trust and relay connectivity. Wake/unlock locally if required; inspect state before repeating input.
Full error reference ↗Action result (driver 502/504)DELIVERY_UNKNOWNDelivery may have happened but its outcome is unconfirmed.
Recovery: Read the original action, then capture/inspect the phone. Do not blindly replay taps, uploads or publication.
Full error reference ↗Action result (driver 503)CONFIGURATIONServer relay transport configuration is invalid.
Recovery: Have the operator repair the relay URL; changing phone credentials will not correct server configuration.
Full error reference ↗Native driver 502/504NATIVE_FAILEDNative ADB/MCP execution failed or exceeded its deadline.
Recovery: Check ADB trust/serial or the native MCP service and connection. Inspect first; the command may already have had effects. The bridge preserves this code in an unknown action result.
Full error reference ↗Native driver 502/504WDA_FAILEDWDA rejected or timed out on an operation.
Recovery: Check WDA signing, running session and connectivity. A later action can re-establish a lost WDA session; inspect before new input. The bridge preserves this code in an unknown action result.
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
| Annotation | Value |
|---|---|
readOnlyHint | false |
destructiveHint | true |
idempotentHint | false |
openWorldHint | true |
