# 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-04)

This page lists every tool of the Macro Automation Studio (MAS) Android MCP server: 25 tools on the hosted server and 13 tools on the local connector. The tables come from the catalog the server is 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 25 tools on your cloud devices. The local connector, `python -m masagent mcp`, exposes 13 tools on any emulator or phone that `adb devices` lists. Those 13 tools exist on both surfaces: `list_devices`, `screenshot`, `screen_size`, `tap`, `swipe`, `type_text`, `press_key`, `open_app`, `close_app`, `current_app`, `read_text`, `find_image` and `wait`. The other twelve, covering leases, macros, runs, agent authoring and app maps, are hosted only.

One parameter differs by surface: on the local connector a device tool accepts an optional `device` serial and falls back to `MAS_DEVICE` or the first device adb lists, while on the hosted server a device tool takes a `lease_id`. `wait` pauses up to 10 seconds per call on the hosted server and up to 60 seconds locally.

## 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; it does not lock the device against a second client. `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 token inherits the scopes ticked on its API key; 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 connector has no auth and no scopes.

| Scope | Tool group |
|---|---|
| `devices:control` | Device control and vision |
| `macros:run` | Macros and runs |
| `macros:author` | Agent authoring |
| `maps:read` | App maps |
| `runs:read` | Reserved; no tool requires it |

## How the Android MCP server tools are grouped

Five groups follow the order of a session. **Device control** picks a device and drives it with taps, swipes, keys and app launches. **Vision** lets the model see: `screenshot` returns image content, `read_text` returns OCR lines with confidence and bounding boxes, and `find_image` returns the score and centre of a template you send. **Macros and runs** reads your library and starts, checks and stops server-side runs on a cloud device. **Agent authoring** hands a goal to MAS Agent and returns a session you can follow, answer and stop. **App maps** reads what the agent learned about an app. Two resources, `mas://docs/sdk-reference` and `mas://docs/house-library`, let a client write macro code in house style.

## How to read the table

Each row names the tool, its parameters, the surface it exists on and the scope it needs, then says what it does. "Local and hosted" means both surfaces; "hosted" means it needs a cloud device. Parameters omit the surface-specific `device` or `lease_id`. Results arrive as text content holding a JSON object, except `screenshot`, which arrives as image content. A failed call returns `isError` true with an `error` message.