# Quickstart with Claude Code

> Give Claude Code a cloud Android phone in two minutes with the AkaPhone MCP server.

Source: https://akaphone-docs.pages.dev/quickstart/claude-code/

The AkaPhone MCP server (`akaphone-mcp` on npm) runs locally next to Claude Code over stdio and turns AkaPhone into 13 tools: create a device, run a task on it, install an APK, tap and type, take a screenshot, snapshot it, and so on. Claude decides when to call them.

You need Node.js 20 or newer (for `npx`) and Claude Code.

## 1. Get an API key

1. Open [https://akaphone.abhgnx-417.workers.dev](https://akaphone.abhgnx-417.workers.dev) and sign in with Google. New accounts start with 60 free credit minutes.
2. Go to **API keys** and click **Create key**. Give it a name such as `laptop-claude-code`.
3. Copy the secret. It looks like `ak_live_urQuj41lKvo2VYp2kBoFqRGw5ig661RoAtM5uTvyrhB` and is **shown only once**. If you lose it, revoke it and create another.

## 2. Get a model key

Tasks are run by the ARTEMIS agent on the device host, and ARTEMIS calls a model with **your** key. The MCP server sends it with each task as the `X-Model-Key` header. AkaPhone never stores it. See [Model keys](https://akaphone-docs.pages.dev/guides/model-keys/).

The default provider is Gemini, so a [Google AI Studio](https://aistudio.google.com/apikey) key (`AIza…`) is the quickest start. To use Claude or OpenAI instead, also set `MODEL_PROVIDER` (below).

## 3. Add the server

```bash
claude mcp add akaphone \
  -e AKAPHONE_API_KEY=ak_live_... \
  -e MODEL_API_KEY=AIza... \
  -- npx -y akaphone-mcp
```

That registers a stdio server named `akaphone` for the current project. Add `--scope user` after `add` to make it available in every project.

| Variable | Required | What it does |
|---|---|---|
| `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 model provider key, sent per task as `X-Model-Key`. Without it, `device_run_task` has no model to use. |
| `MODEL_PROVIDER` | no | `gemini` (default), `anthropic` or `openai`. Sent as `X-Model-Provider`. Any other value stops the server at startup. |

Check it is connected: run `claude mcp list` in a terminal, or type `/mcp` inside Claude Code. The `akaphone` server should be listed as connected.

## 4. First prompts to try

Start a new Claude Code session and paste one of these:

> Create a phone, open Settings > About phone and tell me the Android version and build number. Then terminate the phone.

> Create a phone called "checkout-test". Open Chrome, go to example.com and take a screenshot. Leave the phone running.

> List my phones and how many minutes I have used this month.

> Install ./app/build/outputs/apk/debug/app-debug.apk on checkout-test, open the app and tell me what the first screen says.

> On checkout-test, save a snapshot called "chrome-ready", then terminate it.

## What happens

For the first prompt, Claude typically makes three tool calls:

1. **`device_create`** boots a new Android 14 device and waits until it is `running` (up to 90 seconds; usually much faster when a slot is warm). Billing starts when the device is ready, at 1 credit per started minute.
2. **`device_run_task`** with an instruction like *“Open Settings > About phone and read the Android version and build number”*. ARTEMIS drives the phone step by step. The tool polls every 3 seconds and returns the finished task, including `result` (the agent's answer), `status` and `step_count`. While it runs, you can watch the screen live: open the device in the dashboard.
3. **`device_terminate`** stops the device. Billing stops with it.

Every tool and its arguments are listed in the [MCP tools reference](https://akaphone-docs.pages.dev/mcp/tools/).

> **Leave a phone running between prompts**
>
> Creating a device each time is simple, but if you are iterating on an app, keep one device and tell Claude its name or id. A device stops by itself after 30 minutes with no activity, so a forgotten device costs at most about half an hour.

## Troubleshooting

**The server does not show up in `/mcp`, or shows as failed.**
Run `npx -y akaphone-mcp` in a terminal with `AKAPHONE_API_KEY` set. If it prints `AKAPHONE_API_KEY is required`, the `-e` flag did not reach the server: remove it with `claude mcp remove akaphone` and add it again, keeping `--` before `npx`.

**`AkaPhone API 401` or `unauthorized`.**
The key is wrong or revoked. Keys start with `ak_live_`. Check the key list in the dashboard; revoked keys disappear from it.

**Requests fail to connect or return unexpected 404s.**
Check you are on `akaphone-mcp` 1.0.0 or later (`npx -y akaphone-mcp` fetches the latest). Versions before 1.0.0 defaulted to an older API host; with those, set `-e AKAPHONE_API_URL=https://akaphone.abhgnx-417.workers.dev`. If you set `AKAPHONE_API_URL` yourself, it must be exactly `https://akaphone.abhgnx-417.workers.dev`, with no path.

**`402 insufficient_credits`.**
Your balance is below 1 credit. Buy a pack on the [Billing](https://akaphone-docs.pages.dev/guides/billing/) page.

**`409 concurrency_limit`.**
You already have as many devices as your plan allows (1 on Free). Ask Claude to list and terminate devices you no longer need, or stop them in the dashboard.

**The task fails straight away, or the result mentions an API key.**
`MODEL_API_KEY` is missing, invalid, or for a different provider than `MODEL_PROVIDER`. If the server will not start and its log says `MODEL_PROVIDER must be one of gemini, anthropic, openai`, fix the variable and add the server again.

**`409 conflict: Device already has an active task`.**
One task runs per device at a time. Wait for the current one or cancel it in the dashboard.

**`device_create` returns a device that is still `queued` or `creating`.**
The 90-second wait ran out because no slot was free right away; the tool result says so. Ask Claude to check the device again in a minute. A device that cannot be placed within 10 minutes ends in `error` with `no_capacity` and is never billed.