Android MCP Server Tools Reference: Hosted and Local

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

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.

All 25 hosted tools and 13 local tools

Generated from the same catalog the MCP page uses. "Hosted" is the server at https://api.automationmacro.com/mcp; "Local" is python -m masagent mcp. 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	Hosted	Local	Scope
list_devices	List the devices your client can reach, with their state. On the hosted server that is your cloud devices; on the local connector, whatever adb can see.	none			devices:control
lease_device	Open a control session on one of your cloud devices and get the lease_id every device tool needs. Can boot a stopped device first. Leases expire after ten idle minutes and renew on every call.	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 drags, with a chosen duration.	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 ten seconds per call.	ms			devices:control

Vision

Let the model see the screen and locate things on it without guessing coordinates.

Tool	What it does	Parameters	Hosted	Local	Scope
screenshot	Capture the screen and return it as an image the model can look at.	lease_id			devices:control
read_text	OCR the whole screen or one region into text lines, each with a confidence and a bounding box.	region			devices:control
find_image	Locate a template image on screen with OpenCV matching and return the match score and tap coordinates.	template_base64, threshold			devices:control

Macros and runs

Your macro library, readable and runnable from the client. Runs execute server-side on a cloud device.

Tool	What it does	Parameters	Hosted	Local	Scope
list_macros	List your saved macros with name, id and type, paged.	page, page_size		no	macros:run
get_macro_code	Read a macro's source: the entry script by default, plus the file listing, or any file you name.	macro_id, file		no	macros:run
run_macro	Start a saved macro on a cloud device, server-side, with optional argument overrides. Returns a run_id.	macro_id, device_id, args		no	macros:run
get_run	The state of a run, from launching through running to finished or failed, with its message.	run_id		no	macros:run
stop_run	Stop a running macro.	run_id		no	macros:run

Agent authoring

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

Tool	What it does	Parameters	Hosted	Local	Scope
author_macro	Ask MAS Agent to build a new macro on a cloud device from a plain-language goal. Runs for several minutes and spends AI credits. Returns a session_id.	prompt, device_id, model		no	macros:author
get_agent_session	Progress of an authoring session: state, summary, the macro id once it exists, and the transcript events after your cursor, including any question the agent asked.	session_id, after_seq		no	macros:author
answer_agent_session	Answer the agent's pending question so it can continue.	session_id, qid, answers		no	macros:author
stop_agent_session	Stop a session early. Work done so far is saved.	session_id		no	macros:author

App maps

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

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