MCP setup

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 installs the CLI and signs you in without starting this local MCP server.

Set up with an agent

Paste one prompt and your coding agent does the rest.

Copy setup promptPreview prompt

Setup prompt

Copy

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)Copy Anchor Link

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:

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

Install the plugin, then start a fresh Codex session:

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 CLICopy Anchor Link

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

curl -fsSL https://revyl.com/install.sh | sh

AuthenticationCopy Anchor Link

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 below. See 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.

CursorCopy Anchor Link

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

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

Create .cursor/mcp.json in the repository:

{
  "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:

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 CLICopy Anchor Link

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 clientsCopy Anchor Link

Claude CodeCopy Anchor Link

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

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

CodexCopy Anchor Link

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:

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 updatesCopy Anchor Link

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:

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 installer reads the same packages from the public CLI repository:

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 branchCopy Anchor Link

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.

{
  "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.

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.

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

See Git branch detection for how runs and uploads use the branch.

Launch Configuration InputsCopy Anchor Link

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.

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 recoveryCopy Anchor Link

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 AgentsCopy Anchor Link

Cloud Agents do not inherit the CLI installation or credentials from your local machine. Install the Cursor plugin; 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_requiredCopy Anchor Link

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:

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 fallbackCopy Anchor Link

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:

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:

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 for framework-specific behavior.

VerifyCopy Anchor Link

Start a new agent chat and ask:

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).