MCP Tools Reference

The Revyl MCP server exposes tools across the following categories. Device action tools use grounded targeting by default — describe the element in natural language (target="Sign In button") and coordinates are resolved automatically. You can also pass raw x, y as an override.

Profiles

The tools below are the flat set that revyl mcp serve registers with no --profile. Profiles expose fewer, grouped tools:

dev (recommended in MCP setup): focused setup, dev-loop, and device tools, with sessions under device_session and its action.
core: the device tools, start_dev_loop, manage_tests, and manage_builds. Their action picks the operation and params takes that flat tool’s inputs; for example, manage_tests with action run takes run_test’s inputs in params.
full: core plus manage_workflows and the module, script, tag, file, and variable tools.

Branch and build inputs

MCP inputs name the build choice with build_selection. See How a run picks its build for the model.

`build_selection`	Choice	Runs
`inherit` (default)	Automatic	The branch’s default build: its pinned build, or else its newest
`latest`	Latest build	The branch’s newest build, even when it’s pinned
`latest_all_branches`	All branches · Latest build	The newest build on any of the app’s branches; takes no branch
`pinned`	Exact build	The build ID you pass

A choice passed to one call overrides the saved one for that call only. It never saves a default or pins a branch.
On Default branch, with no branch passed or saved, tools try the Git branch of project_dir or REVYL_PROJECT_DIR first, then the app’s default branch; see MCP setup. Only the Git branch falls back; a branch you name or save, or a pinned or exact build that’s no longer available, fails.
Run and session results name what ran: branch_name, build_id, build_version, branch_source (git_branch, explicit_branch, or default_branch), and git_branch_name, the Git branch the call consulted. default_branch with a git_branch_name means that Git branch couldn’t be used and the app’s default branch ran.

In core and full, the test, build, and workflow tools below are actions of manage_tests, manage_builds, and manage_workflows, such as run_test as manage_tests action run. In dev, device_session with action start takes start_device_session’s branch and build inputs.

Tool	Branch and build inputs
`start_device_session`, `install_app`	`app_id`, `branch_name`, `build_selection`, or exact `build_version_id`, plus `project_dir`.
`start_dev_loop`	`branch_name`, `build_selection` (not `latest_all_branches`), or exact `build_version_id`. The dev loop keeps its branch for rebuilds.
`run_test`	`branch_id` or `branch_name`, `build_selection`, or exact `build_version_id`. Without them, the test’s saved choice.
`create_test`, `update_test`	`branch_id` or `branch_name`, `build_selection`, `pinned_build_id`. Without them, the YAML’s `test.build`; with neither, create saves Default branch and update keeps the saved choice. `inherit` with no IDs saves Default branch.
`upload_build`	`branch_id`, or `branch_name` (created if missing). Without one, the Git branch of `project_dir` or `REVYL_PROJECT_DIR` (created if missing), otherwise the app’s default branch. Never pins. Results include `branch_id`, `branch_name`, and `version_id`.
`list_builds`	With `app_id`, builds on every branch in `versions`; `branch_id` or `branch_name` narrows to one. Without `app_id`, app summaries in `builds`.
`run_workflow`	`branch_name` and `build_selection` (`inherit`, `latest`, or `latest_all_branches`) for every app in the run, or exact `ios_build_id` / `android_build_id` with the matching app.
`set_workflow_app`	`ios_app_id` with `ios_branch_id` or `ios_branch_name`, `ios_build_selection`, and `ios_pinned_build_id`; the same `android_*` fields. `inherit` with no IDs saves Default branch for that platform.

If you pass a branch and an exact build, the build must belong to that branch. MCP tools can’t rename or pin branches or set the default branch; use the CLI or the dashboard (Manage branches).

Device Session

Tool	Description
`start_device_session`	Start an iOS, Android, or Web session; returns its `session_id`
`stop_device_session`	Stop a device session
`get_session_info`	Get session details including viewer URL
`list_device_sessions`	List all active sessions with their `session_id` and index
`switch_device_session`	Switch the active session by index

Targeting a Session

Create a Web app with create_app(name="My Web App", platform="web"). Then start_device_session(platform="web", app_id="YOUR_WEB_APP_ID") selects the app’s latest build. Pass build_version_id to select a specific URL or managed bundle build, or url="https://example.com/" to create or reuse a URL build before starting. Web always requires app_id; session start takes no project input. Managed bundles run in an isolated app container beside Chrome. viewport accepts width, height, and device_scale_factor. Use device_type(text_env="PASSWORD_ENV_NAME", ...) for private password input without putting its value in tool arguments or output. Every tool that acts on a device session accepts an optional session_id next to session_index. Pass the session_id that start_device_session or list_device_sessions returned whenever more than one session may be live, for example when several agents share one MCP server:

session_id selects exactly that session and never falls back to the active one. It also works for a session this server did not start or list. Such a session has no local index, so:
- get_session_info omits session_index.
- Phone screenshots return no screen_token; Web screenshots retain their local observation token.
- On phones, interact can’t ground a drag between two targets; describe the drag with strategy="instruction" instead.
interact keeps every step on the session it started with. If that session ends partway through, the call fails instead of moving to another device.
If you pass both and session_index names a different session, the call fails with an error that names both targets.
With neither, tools use the active session, as before.
get_session_report(session_id=...) also works after the session has ended.

Device Actions

Tool	Description
`device_tap`	Tap an element by target or coordinates
`device_double_tap`	Double-tap an element
`device_long_press`	Long press with configurable duration
`device_type`	Type text into a field
`device_swipe`	Swipe in a direction from a target or point
`device_scroll`	Web: scroll by a bounded pixel amount, optionally at a target or point
`device_select`	Web: choose an enabled native select option by its exact label
`device_drag`	Drag from one point to another
`device_pinch`	Pinch/zoom gesture
`device_clear_text`	Clear text in a field

Device Controls

Tool	Description
`device_wait`	Wait for a fixed duration
`device_back`	Android back button
`device_key`	Press Enter/Backspace on phones; named keys and shortcuts on Web
`device_shake`	Trigger shake gesture
`device_go_home`	Return to home screen
`device_kill_app`	Kill the current app
`device_open_app`	Open a system app by name
`device_navigate`	Open a URL or deep link
`device_set_location`	Set GPS coordinates
`device_download_file`	Download a file to device storage

For Web keyboard checks, use device_key(key="Escape"), device_key(key="Tab"), device_key(key="Enter"), or a chord such as device_key(key="Shift+Tab") or device_key(key="Meta+K"). Named keys are Enter (Return), Backspace, Tab, Escape (Esc), Delete, Space, ArrowUp/Down/Left/Right, Home, End, PageUp, and PageDown. Chords accept distinct Ctrl, Alt, Meta, or Shift modifiers and one named key or ASCII letter/digit. Bare letters/digits and function keys are rejected. Phone Enter/Backspace and Return/Delete aliases are unchanged. device_scroll(direction="down", amount=600) scrolls toward later content; directions are up/down/left/right and amount is 1–16384 pixels (default 600). Optionally pass target or paired x/y; with neither it uses the viewport center. device_select(option_label="Canada", target="Country") matches one enabled native HTML select option by its exact label, not value attribute. Custom dropdowns need normal taps or keys. Both tools refuse phone sessions without sending an action. All three tools accept session_id/session_index; scroll and select also accept an optional screenshot screen_token.

Live Steps

Tool	Description
`device_instruction`	Execute one instruction step (natural-language action)
`device_validation`	Execute one validation step (assertion)
`device_extract`	Execute one extract step (data extraction)
`device_code_execution`	Execute one code execution step by script ID

Vision

Tool	Description
`screenshot`	Capture a screenshot of the current screen

App Management

Tool	Description
`install_app`	Install a selected app/branch build, an exact build, or a URL artifact
`launch_app`	Launch an app; omit `bundle_id` to launch the app the session installed

Diagnostics

Tool	Description
`device_doctor`	Run diagnostics on auth, session, device, and grounding health
`auth_status`	Check authentication status and user info

Test Management

Tool	Description
`run_test`	Run a test by name or ID
`create_test`	Create a new test from YAML content
`update_test`	Update an existing test’s YAML content
`delete_test`	Delete a test by name or ID
`list_tests`	List tests from `.revyl/config.yaml`
`list_remote_tests`	List all tests in the organization
`get_test_status`	Get the status of a running or completed test
`cancel_test`	Cancel a running test by task ID
`get_schema`	Get the CLI command and YAML test schema

Workflow Management

Tool	Description
`run_workflow`	Run a workflow by name or ID
`create_workflow`	Create a new workflow
`delete_workflow`	Delete a workflow by name or ID
`list_workflows`	List all workflows in the organization
`cancel_workflow`	Cancel a running workflow by task ID
`open_workflow_editor`	Get the URL to the workflow browser editor
`add_tests_to_workflow`	Add tests to a workflow
`remove_tests_from_workflow`	Remove tests from a workflow
`get_workflow_settings`	Get workflow location and app overrides
`set_workflow_location`	Set GPS location override for a workflow
`clear_workflow_location`	Remove GPS location override
`set_workflow_app`	Set app overrides per platform
`clear_workflow_app`	Remove app overrides

Module Management

Tool	Description
`list_modules`	List reusable test modules
`get_module`	Get module details and blocks
`create_module`	Create a module from blocks
`delete_module`	Delete a module (fails if in use)
`insert_module_block`	Get a `module_import` YAML snippet for a module

Tag Management

Tool	Description
`list_tags`	List all tags with test counts
`create_tag`	Create a tag (upsert)
`delete_tag`	Delete a tag from all tests
`get_test_tags`	Get tags for a specific test
`set_test_tags`	Replace all tags on a test
`add_remove_test_tags`	Add/remove tags without replacing

Variables and Environment

Tool	Description
`list_variables`	List test variables (`{{name}}` syntax in steps)
`set_variable`	Add or update a test variable
`delete_variable`	Delete a test variable
`delete_all_variables`	Delete all test variables
`list_env_vars`	List environment variables (encrypted, injected at launch)
`set_env_var`	Add or update an env var
`delete_env_var`	Delete an env var
`clear_env_vars`	Delete all env vars

Build Management

Tool	Description
`list_builds`	List app summaries; with `app_id`, list builds across all branches, or on `branch_id` or `branch_name`
`upload_build`	Upload a build file to an app
`create_app`	Create a new app for build uploads
`delete_app`	Delete an app and all its build versions

Script Management

Tool	Description
`list_scripts`	List code execution scripts
`get_script`	Get script details and source code
`create_script`	Create a new script

Dev Loop

Tool	Description
`start_dev_loop`	Start an Expo hot-reload dev loop
`stop_dev_loop`	Stop the active dev loop

Getting Started

CLI

Builds

Tests

Develop

Atlas

Integrations

Device Infrastructure

Appendix

Profiles

Branch and build inputs

Device Session

Targeting a Session

Device Actions

Device Controls

Live Steps

Vision

App Management

Diagnostics

Test Management

Workflow Management

Module Management

Tag Management

Variables and Environment

Build Management

Script Management

Dev Loop

​Profiles

​Branch and build inputs

​Device Session

​Targeting a Session

​Device Actions

​Device Controls

​Live Steps

​Vision

​App Management

​Diagnostics

​Test Management

​Workflow Management

​Module Management

​Tag Management

​Variables and Environment

​Build Management

​Script Management

​Dev Loop

Profiles

Branch and build inputs

Device Session

Targeting a Session

Device Actions

Device Controls

Live Steps

Vision

App Management

Diagnostics

Test Management

Workflow Management

Module Management

Tag Management

Variables and Environment

Build Management

Script Management

Dev Loop