MCP Tools

AndroidUse exposes the phone as an authenticated MCP control plane.

Shell

mksh runs commands in an Android shell. By default, the server keeps a persistent PTY session per MCP HTTP session, so state such as cd and shell variables can survive across tool calls.

UI Control

Routine navigation should prefer ui_dump. It filters redundant XML containers and emits one compact line per core element.

Use screenshots only when visual context is required or ui_dump reports a visual fallback case such as WebView, SurfaceView, TextureView, game/video content, or captcha-like screens.

Screenshot URL Design

screenshot captures the screen into the module state directory and returns a protected HTTP URL directly:

http://127.0.0.1:8765/screenshots/shot-...png

Agents can fetch that URL using the same MCP secret:

curl -H "Authorization: Bearer $ANDROIDUSE_MCP_SECRET" \
  "http://127.0.0.1:8765/screenshots/shot-...png" \
  -o screen.png

This is intentional. Returning a URL avoids extra tool calls where an agent first asks the phone to create a screenshot, then copies a file out through another channel. For clients that cannot attach headers, include_secret_in_url=true returns an additional url_with_secret, but the default avoids putting the secret into model-visible text.

Human Review

• take_over: request user review for login, captcha, payment confirmation, or other sensitive actions.
• human_takeover: hand control to the user for complex screens, then continue after the user marks the takeover complete.

Dynamic Tools

generate_new_hook_tool registers a runtime MCP tool blueprint. Requests are queued under .state/dynamic-tools/requests/ and responses are written under .state/dynamic-tools/responses/. Use dynamic_tool_status before debugging app-side behavior; it reports request age, target package, module response presence, bridge request/response paths, and malformed JSON parse errors.

For a local HTTP regression loop, run tools/closed_loop_mcp_http.sh. It starts a temporary MCP server, verifies tools/list, and calls dynamic_tool_status against seeded request/response state.