MCP tools reference

akaphone-mcp 1.0.0 exposes 13 tools. Your agent picks them from your request. You rarely name them yourself, but knowing what they do helps you ask for the right thing. Setup is in Claude Code and Cursor and Codex.

Most tools return JSON text (the API response, pretty-printed); the exceptions are noted. If the API returns an error, the tool result is marked as an error and reads AkaPhone API <status> <code>: <message>. For 429 responses it also says how many seconds to wait.

Summary#

device_create#

Boots a fresh Android 14 phone and, by default, waits until it is running.

Returns the device object. If the 90 seconds run out while capacity is busy, the API sends X-Wait-Timed-Out: 1 and the tool adds a note: the device is still queued or creating, and the agent should check it again with device_list.

Create a phone called "signup-test".

device_list#

Returns an array of devices. Without include_terminated, only queued, creating, running and stopping devices.

Which phones do I have running?

device_terminate#

Returns the device, now stopping (or terminated if it was queued). Billing stops.

Terminate all my running phones.

device_screenshot#

Returns an image/jpeg image of the current screen, which the agent can look at directly.

Show me what's on the screen of signup-test.

device_input#

Sends one input event to a running device. Coordinates are device pixels: 720×1560 on pixel_8 (profiles_list has the others).

Returns a short confirmation. A missing field for the chosen type (for example a tap without y) is an error before anything is sent. Input does not confirm that the tap had an effect; follow it with device_screenshot.

On signup-test, tap the email field at 360, 640, type test@example.com and press Enter.

device_install_apk#

Uploads a local APK and installs it on a running device, then waits for the result.

The tool creates an upload, PUTs the file straight to storage with the presigned URL, completes the upload, starts the install, and polls the install status for up to 5 minutes.

Returns the install: status installed with the package name, or an error result with status failed and the installer's error. If the install is still pending after 5 minutes, the tool says so; the install continues on the device. Runtime permissions are granted on install. .aab bundles are refused before any upload; build a universal APK first. See Install an APK.

Install ./app/build/outputs/apk/debug/app-debug.apk on signup-test and open it.

device_snapshot#

Returns the snapshot in pending status. It becomes ready after a short while. Your plan's snapshot quota applies, and you can take at most 5 snapshots per hour. See Snapshots.

Snapshot signup-test as "logged-in".

device_restore#

Returns the new device (with the same timed-out note as device_create), or the snapshot list when snapshot_id is omitted. The original device is not touched.

Start a new phone from the "logged-in" snapshot.

device_run_task#

Has ARTEMIS carry out a plain-English instruction on a device. It then polls every 3 seconds until the task finishes or wait_seconds runs out.

The tool sends MODEL_API_KEY and MODEL_PROVIDER from the server's environment as the X-Model-Key and X-Model-Provider headers. The host picks the model for the provider and profile (Model keys). To get structured output back, describe it in the instruction, for example “reply with JSON {version, build}”.

Returns the task with steps, status and result. If the task is still running when wait_seconds runs out, the text ends with (still running; poll with task_status).

On signup-test, open the app, sign up as test+42@example.com with password Test1234!, and tell me what the first screen after sign-up says.

task_status#

Returns the task with its steps. Statuses: queued, running, succeeded, failed, cancelled.

Is that task finished yet?

task_artifacts#

Without download, the tool returns { "files": [...] }. Each file has its id, kind, name, size_bytes and a presigned download url. The URLs are valid for 15 minutes. The files are video.mp4, before.png, after.png, trace.tar.gz and stdout.log. The list is empty for a few seconds after a task ends, while the host uploads the files.

With download, the tool fetches that file through its presigned URL:

Show me the after screenshot of the last task, and the end of its log.

usage#

No arguments. Returns the usage report for the current month: total_minutes, active_devices, minutes per day and per device.

How many device-minutes have I used this month?

profiles_list#

No arguments. Returns the device profiles with id, name, width, height, dpi and android:

[
  { "id": "pixel_8", "name": "Pixel 8", "width": 720, "height": 1560, "dpi": 320, "android": "14" },
  { "id": "pixel_tablet", "name": "Pixel Tablet", "width": 1280, "height": 800, "dpi": 240, "android": "14" },
  { "id": "small_phone", "name": "Small phone", "width": 540, "height": 960, "dpi": 240, "android": "14" }
]

Which device sizes can I use? Start a tablet.

Environment variables#

Tips for prompts#

• Name your devices and refer to them by name. The agent maps names to ids with device_list.
• Ask for a verdict. Ending with “…and tell me PASS or FAIL” makes results easy to scan.
• Ask it to clean up. End with “then terminate the phone” unless you want to keep it.
• Keep secrets out of instructions. Instructions are stored with the task, so use test accounts.