# MCP tools reference

> Every tool the akaphone-mcp server exposes to Claude Code, Cursor and Codex, with arguments, what each returns, the REST call behind it and example prompts.

Source: https://akaphone-docs.pages.dev/mcp/tools/

`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](https://akaphone-docs.pages.dev/quickstart/claude-code/) and [Cursor and Codex](https://akaphone-docs.pages.dev/quickstart/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

| Tool | What it does | REST calls |
|---|---|---|
| [`device_create`](#device-create) | Boot a new Android 14 device | `POST /v1/devices` |
| [`device_list`](#device-list) | List your devices | `GET /v1/devices` |
| [`device_terminate`](#device-terminate) | Stop a device and its billing | `DELETE /v1/devices/:id` |
| [`device_screenshot`](#device-screenshot) | The current screen as an image | `GET /v1/devices/:id/screenshot` |
| [`device_input`](#device-input) | Tap, swipe, type or press a key | `POST /v1/devices/:id/input` |
| [`device_install_apk`](#device-install-apk) | Upload a local APK and install it | `POST /v1/uploads`, `PUT` to storage, `POST /v1/uploads/:id/complete`, `POST /v1/devices/:id/apps`, `GET /v1/devices/:id/apps/:install_id` |
| [`device_snapshot`](#device-snapshot) | Save a device's disk as a snapshot | `POST /v1/devices/:id/snapshot` |
| [`device_restore`](#device-restore) | Boot a new device from a snapshot, or list snapshots | `POST /v1/snapshots/:id/restore`, `GET /v1/snapshots` |
| [`device_run_task`](#device-run-task) | Run a plain-English task and wait for the result | `POST /v1/devices/:id/tasks`, then `GET /v1/tasks/:id` |
| [`task_status`](#task-status) | Get a task | `GET /v1/tasks/:id` |
| [`task_artifacts`](#task-artifacts) | List or fetch a task's video, screenshots, trace and log | `GET /v1/tasks/:id/artifacts` |
| [`usage`](#usage) | Device-minutes this month | `GET /v1/usage` |
| [`profiles_list`](#profiles-list) | Device profiles for `device_create` | `GET /v1/profiles` |

## device_create

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

| Argument | Type | Default | Description |
|---|---|---|---|
| `name` | string | none | Friendly name, up to 64 characters. |
| `profile` | string | `pixel_8` | `pixel_8`, `pixel_tablet` or `small_phone` (see `profiles_list`). |
| `wait` | boolean | `true` | Wait until the device is running, for at most 90 seconds. |

**Returns** the [device object](https://akaphone-docs.pages.dev/api/devices/#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

| Argument | Type | Default | Description |
|---|---|---|---|
| `include_terminated` | boolean | `false` | Also list finished devices (the 200 most recent). |

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

> Which phones do I have running?

## device_terminate

| Argument | Type | Description |
|---|---|---|
| `device_id` | string | The device to stop. |

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

> Terminate all my running phones.

## device_screenshot

| Argument | Type | Description |
|---|---|---|
| `device_id` | string | A running device. |

**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).

| Argument | Type | Used with | Description |
|---|---|---|---|
| `device_id` | string | all | A running device. |
| `type` | `tap`, `swipe`, `text` or `key` | all | The kind of event. |
| `x`, `y` | integer, 0–10000 | `tap` | Where to tap. |
| `x1`, `y1`, `x2`, `y2` | integer, 0–10000 | `swipe` | Start and end points. |
| `ms` | integer, 1–10000 | `swipe` | Duration, default 300. |
| `text` | string, 1–500 characters | `text` | Text to type into the focused field. |
| `key` | `HOME`, `BACK`, `RECENTS`, `ENTER`, `DEL` or `TAB` | `key` | Hardware or navigation key. |

**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.

| Argument | Type | Description |
|---|---|---|
| `device_id` | string | A running device. |
| `file_path` | string | Path to a local `.apk` file, at most 300 MB. |

The tool creates an upload, `PUT`s 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](https://akaphone-docs.pages.dev/guides/install-apk/).

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

## device_snapshot

| Argument | Type | Description |
|---|---|---|
| `device_id` | string | A running device. |
| `name` | string | Optional label, up to 64 characters. |

**Returns** the [snapshot](https://akaphone-docs.pages.dev/api/snapshots/#the-snapshot-object) 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](https://akaphone-docs.pages.dev/concepts/snapshots/).

> Snapshot signup-test as "logged-in".

## device_restore

| Argument | Type | Default | Description |
|---|---|---|---|
| `snapshot_id` | string | none | Snapshot to boot from. **Omit it to list your snapshots instead.** |
| `name` | string | none | Name for the new device. |
| `wait` | boolean | `true` | Wait until the new device is running, for at most 90 seconds. |

**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.

| Argument | Type | Default | Description |
|---|---|---|---|
| `device_id` | string | required | A running device with no active task. |
| `instruction` | string | required | What to do, 1–8,000 characters. |
| `profile` | `"flash"` or `"pro"` | `"pro"` | `flash` for quick, simple actions; `pro` for multi-step work. The REST API's own default is `flash`. |
| `wait_seconds` | integer | `600` | 0–1800. `0` returns at once with the queued task. |

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](https://akaphone-docs.pages.dev/guides/model-keys/#models)). To get structured output back, describe it in the instruction, for example *“reply with JSON {version, build}”*.

**Returns** the [task](https://akaphone-docs.pages.dev/api/tasks/#the-task-object) 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

| Argument | Type | Description |
|---|---|---|
| `task_id` | string | The task. |

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

> Is that task finished yet?

## task_artifacts

| Argument | Type | Description |
|---|---|---|
| `task_id` | string | A finished task. |
| `download` | string | Optional. The `id` (`art_…`) or file name of one artifact to fetch. |

**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:

| File | Returned as |
|---|---|
| `before.png`, `after.png` (screenshots) | an image the agent can see |
| `stdout.log` | text (the last 200 KB if it is longer) |
| `video.mp4`, `trace.tar.gz` | a note with the download URL, since binary files cannot be shown inline |

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

## usage

No arguments. **Returns** the [usage report](https://akaphone-docs.pages.dev/api/usage/) 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`:

```json
[
  { "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

| Variable | Required | Description |
|---|---|---|
| `AKAPHONE_API_KEY` | yes | Your `ak_live_…` key. The server exits at startup without it. |
| `AKAPHONE_API_URL` | no | Defaults to `https://akaphone.abhgnx-417.workers.dev`. |
| `MODEL_API_KEY` | for tasks | Your Gemini, Anthropic or OpenAI key. |
| `MODEL_PROVIDER` | no | `gemini` (default), `anthropic` or `openai`. Any other value stops the server at startup with `MODEL_PROVIDER must be one of gemini, anthropic, openai`. |

## 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.