> ## 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 setup

> Connect Revyl to Cursor, Claude Code, or Codex

Connect Revyl over MCP so your coding agent can run the current app source,
control cloud devices, and verify changes. Custom MCP is optional. The
[Cursor plugin](/integrations/cursor) installs the CLI and signs you in
without starting this local MCP server.

Prompt for your coding agent:

```text
Connect Revyl to this coding agent over MCP.

Read https://docs.revyl.com/agents/mcp.md and follow it. It's the current Revyl guide for this, so prefer it over anything you remember about Revyl.

Sign the CLI in with `revyl auth login` first; run it in the background or a second terminal and give me the approval link while it waits. Then register the local server, `revyl mcp serve --profile dev`, the way the page shows for this agent.

You're done when the server is registered and you've told me how to restart this agent, so a new chat can start a Revyl device session, give me its viewer link, and stop it.

Ask me before anything that needs my login or approval.
```

## Codex plugin (local marketplace)

The Revyl Codex plugin is currently installed from a local exported
`revyl-cli/` folder; it is not yet published as a public Codex marketplace
listing. It supplies a checksum-pinned CLI launcher and two CLI-backed skills,
but no hooks or MCP server.

First add the local marketplace with the absolute path to that exported folder:

```bash
codex plugin marketplace add /absolute/path/to/exported/revyl-cli
```

Install the plugin, then start a fresh Codex session:

```bash
codex plugin add revyl@revyl
```

You can also install **Revyl** from the `revyl` marketplace through `/plugins`.
Ask Codex to run and verify your mobile app, identifying the target environment
and approving the device/build operation. On first use, the skill checks the
pinned launcher version and authentication status; approve its normal Revyl
sign-in flow when prompted. Installation does not run commands or modify your
app source or configuration.

Optional standalone MCP setup remains below. Choose it when you want MCP tools
instead of the plugin's CLI-backed skills.

## Install the Revyl CLI

The Cursor Marketplace plugin installs a pinned CLI through its hooks. For a
manual install, Claude Code, or standalone Codex MCP:

<Tabs>
  <Tab title="macOS and Linux">
    ```bash
    curl -fsSL https://revyl.com/install.sh | sh
    ```
  </Tab>

  <Tab title="Windows PowerShell">
    ```powershell
    irm https://raw.githubusercontent.com/RevylAI/revyl-cli/main/scripts/install.ps1 | iex
    ```
  </Tab>

  <Tab title="Cursor Cloud (manual)">
    ```bash
    curl -fsSL https://raw.githubusercontent.com/RevylAI/revyl-cli/main/scripts/install.sh | sh
    ```
  </Tab>
</Tabs>

## Authentication

Every standalone CLI or MCP setup below starts with `revyl auth login`. It prints an approval URL and
a short code, opens the URL when this machine has a browser, and waits for you
to approve. Approval happens through Revyl rather than a local port, so the same
command works on your laptop, in a cloud agent, over SSH, and in a container —
just open the printed URL wherever you are signed in.

For a machine with nobody present to approve, use `revyl auth login --api-key`
or set `REVYL_API_KEY`. That key is optional unattended authentication, not
required. Hosted agents are covered under
[Cursor Cloud Agents](#cursor-cloud-agents) below. See
[Authentication](/authentication) for the full reference.

The MCP server reads whatever the CLI stored, so authenticating once in a
terminal is enough — the next tool call picks it up without restarting the
session.

## Cursor

<Note>
  The [Cursor plugin](/integrations/cursor) installs the CLI and signs
  you in. It does not start this local MCP server. Optional custom MCP below
  uses a literal command only (`revyl` or `/usr/local/bin/revyl`), never
  `${...}`.
</Note>

From the app repository, authenticate and install the MCP dev-loop skill:

```bash
revyl auth login
revyl skill install --name revyl-mcp-dev-loop --cursor
```

Create `.cursor/mcp.json` in the repository:

```json
{
  "mcpServers": {
    "revyl": {
      "command": "revyl",
      "args": ["mcp", "serve", "--profile", "dev"]
    }
  }
}
```

Restart Cursor if it was already open when you installed the CLI. Start a new
Agent chat and ask:

```text
Run this app on a Revyl device.
```

The `dev` profile exposes 11 focused setup, dev-loop, and device tools,
including `setup_status`. It is intentionally narrower than the `core` and
`full` profiles. Use the CLI or a broader MCP profile for test, workflow, and
other management operations.

The command above explicitly selects the MCP-specific `revyl-mcp-dev-loop`
skill. Running `revyl skill install` without selectors installs the
recommended `revyl-cli-*` skills instead, which are the CLI fallback rather than
this MCP skill.
The Marketplace plugin does not start this server; install the MCP skill only
when you opt into custom MCP.

### How the plugin installs the CLI

Plugin hooks use an explicitly configured `REVYL_BINARY` when present in the
environment. Otherwise they:

1. read the runtime version and per-platform SHA-256 values pinned in the
   plugin release;
2. select the matching macOS, Linux, or Windows asset from the immutable Revyl
   CLI GitHub Release;
3. reuse the versioned cached executable only when its SHA-256 still matches;
4. otherwise adopt an already-installed Revyl CLI — the first of `revyl` on
   `PATH`, `/usr/local/bin/revyl`, `~/.revyl/bin/revyl`, or
   `~/.local/bin/revyl` whose SHA-256 equals the pinned value — by copying it
   into the versioned cache and verifying the copy;
5. download a missing or corrupt executable to a temporary file with a bounded
   timeout and up to three attempts with backoff, verify it, install it
   atomically, and verify the cached file again;
6. copy the verified executable onto a user PATH location without replacing a
   different existing CLI: `~/.revyl/bin/revyl` or `~/.local/bin/revyl` on
   macOS and Linux, and `%USERPROFILE%\.revyl\bin\revyl.exe` or
   `%LOCALAPPDATA%\Revyl\bin\revyl.exe` on Windows. An explicit `REVYL_BINARY`
   override is not published.

The default cache is under `$XDG_CACHE_HOME` or
`$HOME/.cache/revyl/cursor-plugin` on macOS and Linux, and
`%LOCALAPPDATA%\Revyl\cursor-plugin` on Windows. A new plugin runtime pin uses a
new versioned directory. A corrupt cached executable is never run and is
replaced on the next online start. Agent shells still need the published PATH
directories prepended; the cache path is not a `revyl` command.

`sessionStart` is a fast path: if the pin is already cached, it bridges a real
`REVYL_API_KEY` or tells the agent to run `revyl auth login`. The first `revyl`
command may download. When every download attempt fails, the launcher names the
asset it could not fetch and points at `REVYL_BINARY` as the manual override.

## Optional standalone CLI-based MCP clients

### Claude Code

Open a new terminal, authenticate, and run from the app repository:

```bash
revyl auth login
claude mcp add --scope project --transport stdio revyl -- revyl mcp serve --profile dev
revyl skill install --name revyl-mcp-dev-loop --claude
```

### Codex

Use this only when you choose standalone MCP instead of the local Codex plugin.
Open a new terminal, authenticate, and run from the app repository:

```bash
revyl auth login
codex mcp add revyl -- revyl mcp serve --profile dev
revyl skill install --name revyl-mcp-dev-loop --codex
```

### Skill selection, storage, and updates

The examples above select one skill. Repeat `--name` to select several, use
`--cli` or `--mcp` for a family, or use `--all` for every skill. Without a
selector, `revyl skill install` uses the recommended skills that
`revyl skill list` shows. In an interactive terminal, the picker preselects
them, so pressing Enter installs them. In a script, or with `--yes` or
`--json`, they are installed directly and named on stderr; `--json` output adds
`"selection": "default"`. Interactive `revyl init` offers the same preselected
picker. An empty selection skips installation. Without an agent flag or a
detected agent directory, installation targets Cursor and Codex.

By default, packages are shared in `.agents/skills/`. Cursor and Codex discover
that directory directly; Claude Code uses relative per-skill links in
`.claude/skills/`. Selecting one agent does not hide a shared skill from other
agents that read `.agents/skills/`. Add `--global` for user-wide installation
under your home directory. A symlinked shared directory is supported only when
it resolves inside the selected project or home directory.

Use `--copy` when you need independent packages in `.cursor/skills/`,
`.codex/skills/`, or `.claude/skills/`, or when your filesystem cannot create
Claude's compatibility links. On Windows without symlink privileges, select
**Claude Code (copy mode)** in `revyl init`. Shared installation checks link
support before writing packages, so an unsupported filesystem does not leave a
partial install. Shared installation checks all agent directories in the
selected scope, even agents you did not select. Conflicting packages, including
retired auth-bypass platform aliases, are preserved rather than migrated or
pruned. When conflicting packages or missing link support block shared storage,
a noninteractive `revyl skill install` says so on stderr and continues as if
`--copy` were given. An interactive install, or one where a selected agent
already links a selected skill to shared storage, stops before writing instead
and names its recovery: move the listed conflicting packages aside, or use
`--copy` when only Claude's links are unavailable. `--copy` never replaces
existing links.
Move conflicting copies aside to switch to shared storage. Installation does
not write `AGENTS.md` or inject a Cursor rule.

Each installation includes `SKILL.md` and the package's source-authored agent
metadata, references, scripts, and assets when present. Auth-bypass reads only
the reference matching the detected stack, rather than loading every platform
recipe. Auth-bypass and Atlas review require an explicit user request in all
supported clients; ordinary workflows permit implicit invocation.

Inspect or refresh installed packages separately from the CLI binary:

```bash
revyl skill list --installed --json
revyl skill update
revyl skill update revyl-mcp-dev-loop
revyl skill update --global
```

Installed listing covers project and global scopes. Updates default to the
current project and only refresh already-installed, unmodified Revyl-managed
packages. Local edits and unmanaged packages are preserved and reported;
updates never add new skills. `revyl upgrade` leaves skills unchanged.
Ordinary installation also preserves an existing package. Use `--force` only
to deliberately replace a selected package and discard its local edits.

The open [skills](https://skills.sh) installer reads the same packages from the
public CLI repository:

```bash
npx skills add RevylAI/revyl-cli#stable -y
npx skills add RevylAI/revyl-cli#stable --skill revyl-mcp-dev-loop -y
```

Without `--skill`, it offers the recommended skills that `revyl skill list`
shows. `#stable` follows the latest CLI release, while `main` can include
skill changes that are not released yet. `npx skills update` refreshes
packages it installed; `revyl skill update` reports them as not managed by
Revyl and leaves them unchanged.

## Follow your Git branch

MCP tools read the Git branch only of the project you point them at, never the
server's own folder. Set `REVYL_PROJECT_DIR` to your app's folder in the
server's environment, or pass `project_dir` on each call. Without either, runs,
sessions, and uploads use the app's default branch.

Cursor: add `env` to the `revyl` entry in the repository's `.cursor/mcp.json`.
Cursor fills in `${workspaceFolder}`, the folder that holds `.cursor/`, so the
shared file works on every machine. Append your app's subfolder if the app isn't
at the repository root.

```json
{
  "mcpServers": {
    "revyl": {
      "command": "revyl",
      "args": ["mcp", "serve", "--profile", "dev"],
      "env": { "REVYL_PROJECT_DIR": "${workspaceFolder}" }
    }
  }
}
```

Claude Code: add a local-scope entry. It stays private to you and takes
precedence over the repository's shared `revyl` entry.

```bash
claude mcp add --scope local --transport stdio revyl -e REVYL_PROJECT_DIR=/absolute/path/to/your/app -- revyl mcp serve --profile dev
```

Codex: this replaces the `revyl` entry in your own `~/.codex/config.toml`.

```bash
codex mcp add revyl --env REVYL_PROJECT_DIR=/absolute/path/to/your/app -- revyl mcp serve --profile dev
```

See [Git branch detection](/builds/branches#git-branch-detection) for how runs
and uploads use the branch.

## Launch Configuration Inputs

MCP launch tools expose the same startup inputs as the CLI. On
`start_dev_loop`, `start_device_session`, `run_test`, and `run_workflow`, use:

- `profile` on `start_dev_loop` for the named local build profile;
- `platform` on `start_dev_loop` for its `ios` or `android` recipe and device;
- `launch_vars` for stored environment-configuration names or IDs;
- `launch_arg_sets` for stored ordered iOS argument-set names or IDs;
- `launch_arguments` for exact inline iOS argument tokens;
- `launch_env` on `start_device_session` for inline environment variables,
  as an object of keys to values, like the CLI's `--launch-env`; and
- `branch_name`, `build_selection`, and `project_dir` to choose the branch and
  build, as in [Branch and build inputs](/reference/mcp-tools#branch-and-build-inputs).

Inline environment variables override stored ones with the same key. Their
values appear in the conversation, so keep secrets in `launch_vars`.
Arrays preserve their input order. Stored argument sets are flattened first,
then inline tokens are appended. Inline tokens are non-secret.
Android-only launches reject iOS arguments, while mixed workflows skip them for
Android children.

## Setup recovery

The agent calls `start_dev_loop` first. When setup is ready, Revyl returns the
viewer immediately. Otherwise the result contains one structured
`remediation`:

- `auth_required`, `auth_expired`, or `auth_invalid`: run
  `remediation.command` to log in; invalid stored credentials are replaced by
  the successful login before the single retry. Revyl also registers an approval
  for you and returns it as `outcome.authorization_url` and
  `outcome.authorization_code`, so you can approve in a browser without touching
  a terminal — clients that render inline MCP apps show this as an authorize
  button. The accompanying message also names the Cloud secret bridge below,
  which is the recovery to prefer when no one is present to complete a login.
- `cloud_secret_required`: run `remediation.command` to bridge the injected
  `remediation.env_name` secret into the credential store. `restart_required`
  is false, so retry in the same session. When no secret is present the command
  says so; run `revyl auth login` and post the printed approval URL, or add
  optional `REVYL_API_KEY` as a Runtime Secret and start a fresh Cloud Agent.
- `cloud_context_invalid`: when `remediation.action_kind` is `restart_session`,
  start a fresh Cloud session and do not retry in the current session.
- `project_not_initialized`: use `remediation.command` to pull an existing
  UI-created or server-managed project, or `remediation.alternative_command`
  to initialize a genuinely new project. Choose from repository and user
  context; ask when unclear, then run only that exact command in
  `remediation.working_directory`.
- `project_legacy_config`: run `remediation.check_command` to review the
  proposal and complete migration report, then run
  `remediation.apply_command` to create the backup and apply it.
- `project_outside_git`: select a project directory inside an active Git
  worktree and retry with it as `project_dir`.
- `project_ambiguous`: choose one `remediation.candidate_roots` value and retry
  with that exact `project_dir`.
- `project_invalid`: run `remediation.check_command`, repair
  `remediation.config_path`, and retry.

After one remediation, the agent retries `start_dev_loop` once. A second
failure is reported instead of entering a setup loop.

If `start_dev_loop` instead fails with a profile/platform selection error, use
the valid choices in the error to retry once with exact `profile` and
`platform` values. Do not guess or invent a default. The deprecated
`platform_key` input returns `dev_loop_platform_key_removed`; retry with
`profile` and `platform`.

`setup_status` provides the same secret-free setup diagnostics when explicitly
requested, but it is not required before a normal dev loop. Its `signals`
object reports the markers behind the classification without exposing any
secret: whether a Cloud context file was read, whether it failed to parse, and
whether `REVYL_API_KEY` was `absent`, `unresolved`, or `present`. An
`unresolved` value means the host passed its literal interpolation syntax
rather than the secret itself.

## Cursor Cloud Agents

Cloud Agents do not inherit the CLI installation or credentials from your
local machine. Install the [Cursor plugin](/integrations/cursor); its
hooks download the pinned CLI. Then:

1. Ask the agent to run `revyl auth login` and post the approval URL as a
   clickable markdown link, **or** add optional `REVYL_API_KEY` as a Runtime
   Secret for unattended agents.
2. Start a new Cloud Agent so hooks can see the environment.
3. Ask the agent to run the app with a remote build.

If you install the CLI yourself in Cloud setup instead of using the plugin,
use the GitHub raw installer above. Optional custom MCP must use a literal
command (`revyl` or `/usr/local/bin/revyl`), never `${CURSOR_PLUGIN_ROOT}` or
`${env:...}`. Cloud Agents do not start plugin MCP.

### When the agent reports `cloud_secret_required`

A Cloud Agent injects Runtime Secrets into the shell, but the MCP server runs
as a separate process that may not see them. Bridge the secret from a terminal
in the agent:

```bash
revyl auth persist-cloud-env
```

The command copies `REVYL_API_KEY` from the current shell into the credential
store. It reads an existing secret and cannot create one: if no key is present,
run `revyl auth login` and post the printed approval URL, or add optional
`REVYL_API_KEY` as a Runtime Secret and start a fresh Cloud Agent.

Never paste the secret value into chat, a command argument, or a commit. The
bridge reads it from the environment and never prints it.

## Manual CLI fallback

Use the standalone CLI for CI, terminal workflows, unsupported MCP clients,
offline environments, advanced operations, or recovery. Install it with the
platform command above, then run the bounded loop from the app directory:

```bash
revyl auth login
revyl init --non-interactive

# Hot-reload/local build flow.
revyl dev --profile development --platform ios --detach --json --no-open

# Native or Cloud flow using remote builders.
revyl dev --profile development --platform ios --remote --seed-latest --detach --json --no-open

revyl dev status
revyl dev rebuild --wait --timeout 600 --json
revyl device screenshot --out before.png
revyl device validation "The expected screen is visible" --json

revyl dev stop
```

Run from the actual app root in a monorepo. If framework detection is wrong,
rerun detection from that root:

```bash
revyl init --detect
```

If the detected recipe still needs adjustment, edit the named profile in
`.revyl/config.yaml` directly and run `revyl config validate`. For Xcode, pass a
scheme during detection with `--xcode-scheme <platform-key>=<scheme>` so Revyl
embeds it in the generated build commands.

Use `revyl dev list`, explicit contexts, or `revyl dev attach` only when
intentionally reusing an existing session. See the
[full dev-loop guide](https://github.com/RevylAI/revyl-cli/blob/main/docs/developer_loop/dev-loop.md)
for framework-specific behavior.

## Verify

Start a new agent chat and ask:

```text
Run this app on a Revyl device.
```

The agent should share the viewer URL immediately, return device-backed
evidence, and stop the device when finished.

For proving CI-uploaded PR builds with a Cursor Automation (no Revyl GitHub
App), see [Cursor proof (BYO-CI)](/integrations/cursor/proof).