# Android MCP Server Tools Reference: Hosted and Local

> All MAS Android MCP server tools by name, with parameters, the surface each exists on and the scope it needs, for Claude Code, Cursor, Codex or any MCP client.

Source: https://automationmacro.com/docs/mcp/tools (Integrate, updated 2026-09-09)

This page lists every tool of the Macro Automation Studio (MAS) Android MCP server: 41 tools on the hosted server and 38 tools on the local server the desktop app runs. The tables at the end come from the catalog the servers are verified against, so names and parameters match what your client shows after `tools/list`. Client setup is on the [MCP server page](/docs/mcp), and the [MCP overview](/mcp) explains what the server is for.

## The two surfaces: MCP tools for cloud devices and the Android emulator

The hosted server at `https://api.automationmacro.com/mcp` exposes 41 tools on your cloud devices. The local server the desktop app runs at `http://127.0.0.1:<port>/mcp` exposes 38 tools on any emulator or phone the app sees over adb. The two overlap almost completely: only `lease_device`, `release_device` and `get_map` are hosted only, and `get_run` is the hosted name of the local `get_run_status`. Macro runs, agent authoring, the image library, the developer loop and scheduling exist on both; the local server does them with the app's own catalogue, Image Library and scheduler.

Each table has a **Cloud** and a **Local** column. A tick in both means the tool exists on both surfaces under the same name; "no" under Local marks the three hosted-only tools, and "no" under Cloud marks `get_run_status`.

## How a device is referenced

The one argument that always differs by surface is the device.

- **Hosted server:** every device tool takes the `lease_id` that `lease_device` returned. Tools that start work on a device rather than drive it, `run_macro`, `validate_macro`, `author_macro` and `schedule_macro`, take the numeric `device_id` from `list_devices` instead, and lease nothing.
- **Local server:** every device-bound tool takes `device`: the id from `list_devices` (`emulator-21513`), an adb serial (`127.0.0.1:21513`) or the bare port (`21513`). Omit it when exactly one emulator is running; with several running, a missing `device` is an error that lists them. `desktop` is refused.

The tables leave that argument out of **Parameters**; everything else a tool takes is listed.

## What an MCP device lease is

`lease_device` opens a control session on one of your cloud devices and returns a `lease_id`, which every device tool on the hosted server requires. Set `auto_start` to boot a stopped device first. A lease renews on every call and expires after 10 idle minutes, so a vanished client cannot hold a device forever. One lease per device at a time; a device with a macro run in progress cannot be leased until the run ends, and while it is leased the idle reaper leaves it alone. `release_device` ends the session and the device keeps running. If a call answers "lease not found or expired", lease the device again.

## MCP scopes

A key carries the scopes ticked when it was created; no scopes ticked means full access. The hosted server checks the scope before each call and returns an error result when it is missing. The local server has no auth and no scopes; it answers only your own machine while the app is open.

| Scope | Tool groups |
|---|---|
| `devices:control` | Device control, screen understanding, the image library |
| `macros:run` | Macros and runs (including `validate_macro` and `get_run_log`), scheduling |
| `macros:author` | Agent authoring, `scaffold_macro` and `install_macro` |
| `maps:read` | App maps |
| `runs:read` | Reserved; no tool requires it |

## How the Android MCP server tools are grouped

Nine areas follow the order of a session, and the tools list in that order.

- **Status** is the first call of a session: `get_status` reports what the server can do right now and why a tool might fail. On the hosted server that is your subscription and AI credits, your cloud devices and their states; on the local server it is whether the app is signed in and subscribed, the emulators it sees, the selected AI provider and the clients connected. Read-only and free, with the same body as the `mas://status` resource.
- **Device control** picks a device and drives it: taps, swipes, long presses, drags, typing, keys, app launches, `screen_size` and `wait`. `wait` pauses up to 10 seconds per call on the hosted server and up to 60 seconds locally; prefer `wait_for` when you know what you are waiting for.
- **Screen understanding** lets the model see. `screenshot` returns image content, with `max_width` to shrink it and a reported scale so taps stay in device pixels. `read_text` returns OCR lines; `find_image` matches a template you send inline or an `image_id` from your library and returns the score and centre. `get_ui_tree` renders the accessibility hierarchy as compact text, `find_element` searches it by id, text, description or class, and `wait_for` polls until an image, a text or an element appears.
- **Macros and runs** reads your library (`list_macros`, `get_macro_code`) and starts, checks and stops runs (`run_macro`, `get_run` or `get_run_status`, `stop_run`, `get_run_log`). Hosted runs execute server-side on a cloud device; local runs are the editor's Run button on your emulator.
- **Image library** is the Image Library the app shows: `list_images`, `get_image`, and `crop_image`, which cuts a region of the current screen into a template and returns its `image_id`.
- **Agent authoring** hands a goal to MAS Agent (`author_macro`) and follows the session (`get_agent_session`, `answer_agent_session`, `stop_agent_session`).
- **Developer loop** is for a client that writes the macro itself: `scaffold_macro` for the house skeleton, `install_macro` to create or update a code macro from files, `validate_macro` to run it and get the verdict.
- **App maps** reads what the agent learned about an app (`get_map`, hosted only).
- **Scheduling** creates, lists and cancels jobs in the same scheduler the app's Schedule card uses (`schedule_macro`, `list_schedules`, `cancel_schedule`).

Both servers also publish three resources, `mas://status`, `mas://docs/sdk-reference` and `mas://docs/house-library`, and two prompts, `write-macro` and `debug-run`, listed after the tool tables. The [MCP server page](/docs/mcp) walks through the developer loop end to end.

## Where the two servers differ

The names match, but a handful of arguments and reply shapes do not. Where the local server's arguments differ, the table shows them on a second line under **Parameters**.

| Tool | Hosted server | Local server |
|---|---|---|
| `get_status` | Your subscription and AI credits, your cloud devices and their states, and a hint that local emulators live behind the desktop app | Whether the app is signed in and subscribed, the emulators it sees, the selected AI provider, the endpoint and the connected clients |
| `list_devices` | Your cloud devices and quota | The emulators the app sees: id, serial, port, type, whether a macro is using one |
| `screenshot` | Full-resolution frame unless `max_width` is passed; the scale follows the image only then | Downscaled to 1280 px on the long side unless `max_width` is passed; always reports the scale |
| `read_text` | One confidence and bounding box per line | The lines plus the scanned box |
| `press_key` | Key names and `KEYCODE_*` | Key names, `KEYCODE_*` and numeric keycodes |
| `list_macros` | `page`, `page_size` | `query`, `limit` |
| `get_macro_code` | `file` | `path` |
| `run_macro` | `device_id`; poll with `get_run` (numeric `run_id`) | `device`; poll with `get_run_status` (string `run_id`); the emulator stays busy for the other device tools until the run ends |
| `get_run_log` | `max_lines` (default 200) | `tail` (default 100) |
| `list_images` | `folder`, `query`, `limit`, `page` | `folder`, `query`, `limit` |
| `author_macro` | `device_id`; always the metered MAS cloud model, `model` picks one | `device`; `provider` and `model` pick the brain, otherwise the app's current selection |
| `get_agent_session` | `after_seq`; returns the transcript events after your cursor | Returns state, the pending question and `installed_macro_id` |
| `answer_agent_session` | `qid` plus an `answers` object keyed by question header | One `answer` string |
| `install_macro` | `files` only | `files` or `project_dir`, a folder on your PC |
| `validate_macro` | `macro_id`, `device_id`, `timeout_s`, `args`: one run, verdict from the exit code | `macro_id` or `project_dir`, `device`, `runs` (1 to 5), `timeout_s`: the app's validation job, which also checks `task.yaml` |
| `schedule_macro` | `device_id`; the job runs with your PC off | `device`; the job fires only while the app is open |
| `wait` | Up to 10 seconds | Up to 60 seconds |

## What a tool needs on the cloud

On the hosted server three groups of tools depend on more than a lease.

- `get_ui_tree`, `find_element` and `wait_for` with an element target need a cloud device on the current device image; an older box answers "this device's box agent predates dump_hierarchy", and `screenshot`, `read_text` and `find_image` keep working on it.
- `crop_image`, `validate_macro` and `schedule_macro` need a cloud device of yours; `crop_image` also needs the lease.
- `run_macro`, `validate_macro` and `schedule_macro` refuse a legacy block macro; only code macros run.

On the local server every tool works on any emulator the app sees, with the app open and signed in.

## How to read the tables

Each row names the tool, says what it does, lists its parameters, ticks the surfaces it exists on and names the scope the hosted server checks. A caveat, when one applies, sits under the description. Results arrive as text content holding a JSON object, except `screenshot`, `get_image` and `crop_image`, which include image content, and `get_ui_tree`, which returns plain text. A failed call returns `isError` true with an `error` message; on the local server a missing `device` with several emulators running lists them in that message.