MCP tools reference

akaphone-mcp 1.1.1 exposes 15 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. AI is included: device_run_task needs no model key.

Recommended: the hosted remote connector, https://app.akaphone.ai/mcp (also reachable as https://app.akaphone.ai/mcp, and set up from Connect to Claude in the dashboard). It signs in with OAuth, needs no install and no API key, and has the same tools; its waits are capped at 25 seconds. The stdio package is optional: npx -y https://akaphone.ai/mcp/akaphone-mcp-1.1.1.tgz (it is not on the npm registry).

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: running and starting phones (queued, creating, running), phones being saved (stopping, saving) and stopped phones with saved data (stopped, with data.bytes and data.saved_at). Deleted phones appear only with include_terminated.

Which phones do I have, and which ones are stopped?

device_terminate#

Returns the device, now stopping; it moves on to saving and then stopped on its own, and data.generation goes up by one. Billing stops at once. A phone that was still queued or booting comes back stopped (or terminated, if it was new and had never been saved).

Stop all my running phones.

device_start#

Resumes a stopped phone from its latest save. It can start on any host; the host restores the saved data and boots it.

Returns the device, normally running, with the same timed-out note as device_create if the wait ran out. A phone that is not stopped (for example still saving) gives a 409 conflict error; so does being over your plan's saved-phone limit. Credit and concurrency checks are the same as for device_create.

Start checkout-test again and check I'm still signed in.

device_delete#

Deletes a phone permanently: stops it without saving if it is running, and erases all of its saved data. Cannot be undone.

Returns the device in status terminated. Use it to clean up throwaway phones and to make room when you hit your plan's saved-phone limit (Free 3, any pack 20, Scale 50, Enterprise 500).

Delete the phones I used for yesterday's test runs.

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 [email protected] 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. Snapshots are portable: device_restore can boot any number of new phones from one, on any host. Your plan's snapshot quota applies, and you can take at most 5 snapshots per hour. See Snapshots. You do not need a snapshot just to keep a phone's data: device_terminate already saves it.

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 task runs on the included AI (no key needed; it counts toward your plan's daily AI tasks). Optional: with the stdio package, MODEL_API_KEY and MODEL_PROVIDER in the server's environment are sent as the X-Model-Key and X-Model-Provider headers to use your own key instead. 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 [email protected] 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 stop the phone” to keep it for later (stopped phones cost nothing), or “then delete the phone” for a throwaway one.
• Keep secrets out of instructions. Instructions are stored with the task, so use test accounts.