Android MCP Server Tools Reference: Hosted and Local

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, and the MCP overview 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.

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

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.

All 41 cloud tools and 38 local tools, by area

Generated from the same catalog the MCP page uses. "Cloud" is the hosted server at https://api.automationmacro.com/mcp; "Local" is the server the desktop app runs at http://127.0.0.1:<port>/mcp. Parameters omit the device reference (lease_id on the cloud, device locally); where the local server takes different arguments, its shape follows on a second line. Scopes apply to the hosted server only.

Device control

Pick a device and drive it: the same taps, swipes and keys a person would use.

Tool	What it does	Parameters	Cloud	Local	Scope
get_status	Call this first. What the server is, whether the account can run anything (subscription, AI credits), the devices it can reach, and hints, including that local emulators are only reachable through the desktop app's local server. The same body as the mas://status resource; needs no scope.	none			none
list_devices	List the devices the server can reach, with their state. On the hosted server that is your cloud devices and quota; on the local server, the emulators the app sees over adb (id, serial, port, whether a macro is using one).	none			devices:control
lease_device	Open a control session on one of your cloud devices and get the lease_id every device tool needs. auto_start boots a stopped device first. A lease renews on every call and expires after ten idle minutes; one lease per device, and a device that is running a macro cannot be leased.	device_id, auto_start		no	devices:control
release_device	End the control session. The device keeps running.	lease_id		no	devices:control
tap	Tap the screen at device coordinates.	x, y			devices:control
swipe	Swipe between two points for scrolling and flicks, with a chosen duration (default 300 ms).	x1, y1, x2, y2, duration_ms			devices:control
long_press	Press and hold at a point for duration_ms (default 800, 100 to 5000): context menus, drag handles, app icons.	x, y, duration_ms			devices:control
drag	Touch down, move to a second point over duration_ms (default 600, 100 to 5000) and release: slow enough for sliders and drag-and-drop, unlike a flick swipe.	x1, y1, x2, y2, duration_ms			devices:control
type_text	Type text into the focused input field.	text			devices:control
press_key	Press BACK, HOME, ENTER, TAB, DEL or any KEYCODE_ name.	key			devices:control
open_app	Launch an app by package name.	package			devices:control
close_app	Force-stop an app by package name.	package			devices:control
current_app	Report the package in the foreground.	none			devices:control
screen_size	Return the screen size in pixels, the coordinate space for tap and swipe.	none			devices:control
wait	Pause for animations and loading screens: up to 10 seconds per call on the hosted server, up to 60 seconds locally. Prefer wait_for when you know what you are waiting for.	ms			devices:control

Screen understanding

Let the model see the screen and locate things on it without guessing coordinates: pixels, OCR, template matching and the accessibility tree.

Tool	What it does	Parameters	Cloud	Local	Scope
screenshot	Capture the screen and return it as an image the model looks at directly. Pass max_width (200 to 2000) for a smaller image; the reply then reports the scale, and tap coordinates stay in device pixels (device_x = image_x / scale). The local server limits the long side to 1280 px by default and always reports the scale.	max_width			devices:control
read_text	OCR the whole screen or one region into text lines. The hosted server returns a confidence and a bounding box per line; the local server returns the lines and the scanned box.	region {x1, y1, x2, y2}			devices:control
find_image	Locate a template on screen with OpenCV matching and return the score and tap coordinates. The template is inline (template_base64) or an image_id from your image library, so a crop made once with crop_image is found every time.	template_base64 | image_id, threshold			devices:control
get_ui_tree	The Android accessibility hierarchy as compact text, one visible element per line with its class, id, text, description, bounds and flags. Cheaper and more exact than a screenshot for buttons, fields and labels; games and canvas views expose little. Cloud: needs an up-to-date device image (a box run-agent that answers dump_hierarchy); an older box says so in the error.	max_nodes			devices:control
find_element	Find UI elements by resource id, text, content description and/or class (selectors combine). Returns the match at index with its bounds and tap centre, plus up to 20 matches. contains=true (default) matches substrings. Cloud: needs an up-to-date device image (a box run-agent that answers dump_hierarchy); an older box says so in the error.	id, text, desc, class, contains, index			devices:control
wait_for	Poll the screen until one target appears or timeout_ms (default 15000, max 60000) passes: a library image (image_id) or inline template, on-screen text (OCR), or a UI element selector. Returns where it was found and the elapsed time. Use it instead of wait plus screenshot loops. Cloud: the element target needs the up-to-date device image (see get_ui_tree).	image_id | template_base64 | text | element {id, text, desc, class}, threshold, timeout_ms, interval_ms			devices:control

Macros and runs

Your macro library, readable and runnable from the client. Hosted runs execute server-side on a cloud device; local runs are the editor's Run button on your emulator.

Tool	What it does	Parameters	Cloud	Local	Scope
list_macros	List your saved macros with name, id and type (code, or legacy for a retired block macro).	page, page_size local: query, limit			macros:run
get_macro_code	Read a code macro's project: the entry script and the file listing by default, or one file you name.	macro_id, file local: macro_id, path			macros:run
run_macro	Start a saved code macro with optional argument overrides and return a run_id at once. Hosted: server-side on a cloud device of yours (it starts if stopped). Local: on the named emulator, which stays busy for the other device tools until the run ends.	macro_id, device_id, args local: macro_id, device, args			macros:run
get_run	The state of a hosted run, from launching through running to finished or failed, with its message and timings.	run_id		no	macros:run
get_run_status	The state of a local run (running, stopping, completed, failed, stopped), its timestamps and the exit code once it ended. The local name for get_run.	run_id	no		macros:run
stop_run	Stop a running macro.	run_id			macros:run
get_run_log	The trailing stdout and stderr lines of a run, newest last, while it runs or after. Hosted runs come from run_macro, validate_macro or a schedule.	run_id, max_lines local: run_id, tail			macros:run

Image library

Your Image Library, the same one the app shows: crop a control once, then find it by id from any tool or macro.

Tool	What it does	Parameters	Cloud	Local	Scope
list_images	List your library images, newest first, optionally within one folder or matching a name substring; each with id, name, folder, pixel size and byte size.	folder, query, limit, page local: folder, query, limit			devices:control
get_image	Fetch one library image by id: the picture itself, to confirm it is the template you mean, plus its name, folder and size.	image_id			devices:control
crop_image	Crop a rectangle of the device's current screen into the library as a PNG template and return its new image_id with a small preview. The region is clamped to the screen; at least 8 by 8 pixels must remain; a name already used in the folder gets a numeric suffix. Cloud: needs a hosted device of yours.	region {x, y, width, height}, name, folder			devices:control

Agent authoring

Hand a goal to MAS Agent and get a finished macro back, from any client.

Tool	What it does	Parameters	Cloud	Local	Scope
author_macro	Ask MAS Agent to build a macro from a plain-language goal: it explores the app on the device, captures what it needs, writes and validates the macro. macro_id improves one of your macros instead, parent_session_id continues an earlier session, pipeline picks how the code is produced (build, review, author, author_fast). Async and minutes long; returns a session_id. Hosted authoring always uses the metered cloud model; local authoring uses the provider the app has selected (provider overrides it).	prompt, device_id, model, macro_id, parent_session_id, pipeline local: prompt, device, provider, model, macro_id, parent_session_id, pipeline			macros:author
get_agent_session	Progress of an authoring session: state, summary, the macro id once it exists, and any question the agent is waiting on. Hosted sessions also return the transcript events after your cursor.	session_id, after_seq local: session_id			macros:author
answer_agent_session	Answer the agent's pending question so it can continue. Hosted: qid plus an answers object keyed by question header; local: one answer string (an option label or free text).	session_id, qid, answers local: session_id, answer			macros:author
stop_agent_session	Stop a session early. Work done so far is saved.	session_id			macros:author

Developer loop

Write a macro yourself, in the house style: scaffold the project, install it as a code macro, prove it with one run.

Tool	What it does	Parameters	Cloud	Local	Scope
scaffold_macro	Generate the house project skeleton for a new code macro: src/app.py wiring, one src/activities/<name>.py stub per activity, common_logic.py, the scheduler library, task.yaml, ui.xml, requirements.txt and README.md. Pure: nothing is saved; returns {files: {path: content}} for you to fill in.	name, activities, description, app_package			macros:author
install_macro	Create a code macro from project files, or replace the code of one of yours when macro_id is given, through the same create and code-sync path the app uses. files is {path: content}, 2 MB total; the code is syntax-checked on intake. The local server also takes project_dir, a folder on your PC.	name, files, macro_id, description local: name, project_dir | files, macro_id, description			macros:author
validate_macro	Run a macro once and wait for the verdict: passed, exit code and the log tail. Hosted: one run on a cloud device, default 300 s; a run still going at the timeout is stopped. Local: the engine's validation job on your emulator, which also checks task.yaml; pass macro_id or project_dir, and runs (1 to 5) for the graduation ladder. Cloud: needs a hosted device of yours.	macro_id, device_id, timeout_s, args local: device, macro_id | project_dir, runs, timeout_s			macros:run

App maps

What the agent has learned about an app, readable by your client.

Tool	What it does	Parameters	Cloud	Local	Scope
get_map	The learned menu map of an app: its screens and the proven routes between them.	package, profile		no	maps:read

Scheduling

The same scheduler the app's Schedule card uses. Hosted jobs run on a cloud device with your PC off; local jobs fire while the app is open.

Tool	What it does	Parameters	Cloud	Local	Scope
schedule_macro	Schedule a code macro to run without you: once at `at` (RFC 3339) or recurring with every = daily, weekly (with weekdays) or monthly, in an IANA timezone. No hourly recurrence: a macro that repeats within the day recurs itself. Missed occurrences are skipped; the job pauses after three consecutive failures. Returns job_id and next_run_at. Cloud: needs a hosted device of yours. Local: the job fires only while the desktop app is open.	macro_id, device_id, at, every, timezone, name, weekdays local: macro_id, device, at, every, timezone, name, weekdays			macros:run
list_schedules	Your scheduled jobs, cloud and local, with status, next and last run, failures and the auto-pause reason. Filter by status or target.	status, target, page			macros:run
cancel_schedule	Delete a scheduled job for good; a run still going on a cloud device is stopped first. Use the app to skip one occurrence or pause a job.	job_id			macros:run

Resources and prompts

Both servers publish the same two resources (resources/list, resources/read) and the same two prompts (prompts/list, prompts/get).

Resource	What it holds	Cloud	Local
mas://status	Read first: the server, the account (subscription, AI credits), the devices it reaches, connected clients on the local server, and where local emulators live (the desktop app).
mas://docs/sdk-reference	The complete reference of the pre-installed mas SDK macros are written against: device control, vision, elements, app management, storage, types and exceptions.
mas://docs/house-library	The house library MAS Agent builds macros with: the scheduler skeleton, the activity runner and the runtime-UI template that scaffold_macro ships verbatim.

Prompt	Arguments	What it does	Cloud	Local
write-macro	goal, app_package	Briefs a model on the house conventions before it writes a macro: layout, the activity contract, the rules that fail device runs, and the scaffold, install, validate loop.
debug-run	run_id	Walks a model through diagnosing a failed or stuck run from its state and log, then fixing and re-validating.