> ## Documentation Index
> Fetch the complete documentation index at: https://docs.revyl.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/agents/mcp)): 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](/builds/branches#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](/agents/mcp#follow-your-git-branch). 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](/builds/branches#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

<Note>
  Web is in alpha. To add it to your organization, email [support@revyl.ai](mailto:support@revyl.ai).
</Note>

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 |