app_session

This tool on every surface: CLI · MCP · Python · JavaScript · Go · Java · .NET

Start or end the session on a device. Every other tool opens a session on first use, so this is never required; it is for putting the slow first start — installing UiAutomator2, building WebDriverAgent on an iPhone — where you asked for it, and for ending one device's session without stopping the daemon. "start" opens it (or keeps one already open, reported as reused) and, given an app, launches it fresh — stopped first if it was running, so the session begins at the app's first screen; its data is kept — and waits for it to be in front. "end" closes it with the daemon's own teardown: accessibility settings put back, a recording or route stopped, WebViews detached, the device-side server stopped, and the device's refs and dialog rules forgotten — and the app start launched, if it did, is stopped; apps it did not launch are left alone. A browser restores its tabs when it next launches, so on Android the tabs app_open_url opened in it are closed first; Safari's cannot be closed from outside. Ending a session that is not open succeeds and says so. "status", or no action, lists the sessions open.

Changes the device, the app or the session: readOnlyHint is false.

Arguments

Name	Type	Required	What it is
action	string: start, end, status		"start", "end" or "status". Omit to read the status.
app	string		With start: a package name or bundle id to launch fresh once the session is up — stopped first if running, data kept.
device	string		Device serial to target, e.g. "emulator-5554". Omit when only one device is running.
driver	string: uiautomator2, uiautomator, wda		Driver to use: "uiautomator2" (default for Android; fast, installs a server APK on first use), "uiautomator" (Android, installs nothing, slower, cannot type), or "wda" (WebDriverAgent: iOS simulators and iPhones).
platform	string: android, ios		"android" or "ios". With start, "ios" picks wda, so a driver need not be named.

Examples

Each is the arguments of a tools/call request; the first is shown whole.

Start a session and launch the app fresh

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "app_session",
    "arguments": {
      "action": "start",
      "app": "com.android.settings"
    }
  }
}

On an Android 15 emulator the answer's text was:

session already open on emulator-5554 (android, uiautomator2); com.android.settings was launched fresh and is in the foreground

End it, putting back what it changed

{
  "action": "end"
}

On an Android 15 emulator the answer's text was:

session ended on emulator-5554; anything it changed for the session is put back; com.android.settings, which the session launched, was stopped