Tools Reference
Every tool the MCP server exposes, with its parameters and return shape.
All tools return pretty-printed JSON as their text payload. Failures come back as an error result the agent can read and react to — a failing tool never tears down the server, so an agent can recover and retry.
The MCP server is a new, beta capability. The tool surface may change.
dcd_list_devices
Discover the devices, OS versions, and Maestro versions available to your organisation. Agents should call this before dcd_run_cloud_test so they pass valid device values.
Takes no parameters.
Returns { ios, android, androidPlay, maestro }, where each platform maps an OS version to its supported device list. See Devices & OS Versions and Maestro Versions.
dcd_list_runs
List recent flow uploads for your organisation, most recent first.
name
string
Filter by upload name. Supports a * wildcard, e.g. nightly-*
from
string
Only uploads created on or after this ISO 8601 date, e.g. 2024-01-01
to
string
Only uploads created on or before this ISO 8601 date
limit
integer
Maximum uploads to return, 1–100 (default 20)
offset
integer
Uploads to skip, for pagination (default 0)
Returns { uploads: [{ id, name, created_at, consoleUrl }], total, limit, offset }. Use a returned id with dcd_get_status or dcd_download_artifacts.
dcd_get_status
Get the status and per-test results of a single upload. This is the polling primitive: after an async dcd_run_cloud_test, call this until status leaves PENDING / QUEUED / RUNNING.
uploadId
string
UUID of the upload, as returned by dcd_run_cloud_test or dcd_list_runs
name
string
Name of the upload to look up
Provide exactly one of uploadId or name — passing both, or neither, is an error.
Returns { status, name, createdAt, tests: [{ name, status, durationSeconds, failReason }] }.
dcd_download_artifacts
Download a completed run's artifacts (the videos/logs zip) and/or a formatted report to local disk. It reads cloud state and writes local files, so it stays available in read-only mode.
uploadId
string
Required. UUID of the upload to download artifacts for
type
ALL | FAILED
Which tests to include artifacts for (default ALL)
artifactsPath
string
Where to write the artifacts zip (default ./artifacts.zip)
report
junit | allure | html
Also download a formatted report of this type
reportPath
string
Where to write the report (defaults by type: report.xml for junit, otherwise report.html)
Returns { uploadId, artifactsPath, reportPath, warnings }. A non-empty warnings array means a download could not be produced — most often because the run has no results yet. An empty array means success. See Artifacts & Downloads and Report Formats.
dcd_run_cloud_test
Submit a Maestro flow, or a directory of flows, to run on DeviceCloud.
This tool consumes test credits. It's annotated as destructive so clients can prompt before calling it, and it's hidden entirely in read-only mode.
flowFile
string
Required. Path to a Maestro .yaml/.yml flow, or a directory of flows
appFile
string
Path to a local app binary — .apk, .app, or .zip. Mutually exclusive with appBinaryId
appBinaryId
string
ID of a previously uploaded binary. Mutually exclusive with appFile
iosVersion
string
iOS version, e.g. 17
iosDevice
string
iOS device, e.g. iphone-14
androidApiLevel
string
Android API level, e.g. 34
androidDevice
string
Android device, e.g. pixel-7
name
string
A name for this run
includeTags
string[]
Only run flows with these tags
excludeTags
string[]
Skip flows with these tags
excludeFlows
string[]
Flow paths/patterns to exclude
ignoreShaCheck
boolean
Force re-upload of the binary even if an identical one already exists
dryRun
boolean
Preview which flows would run, without submitting
wait
boolean
Block until the run completes instead of returning immediately (default false)
waitTimeoutSeconds
integer
Max seconds to wait when wait is true, 30–3600 (default 600)
You must provide either appFile or appBinaryId — not both, and not neither. Use dcd upload or a previous run to get a reusable appBinaryId.
Async by default
By default the tool returns as soon as the run is submitted:
Poll dcd_get_status with that uploadId until the status is terminal. This is the recommended shape for agents — it keeps the tool call short and avoids a long-blocking request.
Set wait: true to block instead. The tool polls every 10 seconds up to waitTimeoutSeconds, then returns with timedOut: true if the run hasn't finished. The run continues in the cloud regardless — a timeout is not a cancellation, and you can resume by polling dcd_get_status with the returned uploadId.
Previewing a run
dryRun: true resolves the flows and returns them without submitting anything or spending credits:
This is a cheap way for an agent to confirm it's about to run the flows you expect before it calls the billable path for real.
Last updated