MCP
MCP tools
The tools the Revyl MCP server exposes, by profile and category.
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 underdevice_sessionand itsaction.core: the device tools,start_dev_loop,manage_tests, andmanage_builds. Theiractionpicks the operation andparamstakes that flat tool's inputs; for example,manage_testswith actionruntakesrun_test's inputs inparams.full:coreplusmanage_workflowsand 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_dirorREVYL_PROJECT_DIRfirst, 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, ordefault_branch), andgit_branch_name, the Git branch the call consulted.default_branchwith agit_branch_namemeans 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 a Web (alpha), iOS, or Android 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
Web is in alpha. To add it to your organization, email support@revyl.ai.
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_idselects 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_infoomitssession_index.- Phone screenshots return no
screen_token; Web screenshots retain their local observation token. - On phones,
interactcan't ground a drag between two targets; describe the drag withstrategy="instruction"instead.
interactkeeps 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_indexnames 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 |