Skip to main content
Connect Revyl over MCP so your coding agent can run the current app source, control cloud devices, and verify changes.

​
Install the Revyl CLI

The Revyl Cursor Marketplace plugin is coming soon. Until it launches, Cursor, Claude Code, and Codex connect through the Revyl CLI. Install the Revyl CLI:

​
Authentication

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

​
Cursor

Coming soon: the official Revyl Marketplace plugin will bundle the MCP configuration, focused skills, routing rule, hooks, and a pinned Revyl runtime. For now, use the CLI-based setup below.
From the app repository, authenticate and install the MCP dev-loop skill:
Create .cursor/mcp.json in the repository:
Restart Cursor if it was already open when you installed the CLI. Start a new Agent chat and ask:
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 installs the MCP-specific revyl-mcp-dev-loop skill. The default revyl skill install command installs the separate revyl-cli-* fallback family and is not required for this MCP setup. When the Marketplace plugin launches, it will bundle its MCP skills automatically; do not install a second copy.

​
How the Marketplace plugin runtime will work

When Cursor starts the future plugin MCP server, the plugin launcher will use an explicitly configured REVYL_BINARY when present. Otherwise it will:
  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. start the MCP server over the same protected standard input and output streams.
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. The first start of a new runtime needs access to its GitHub Release unless a checksum-matching Revyl CLI is already installed on the machine; later starts can use the verified cache. When every download attempt fails, the launcher names the asset it could not fetch and points at REVYL_BINARY as the manual override. Bootstrap failures are written only to standard error so they cannot corrupt MCP messages. The plugin readiness hook reports missing prerequisites but never downloads or installs software itself.

​
Other CLI-based MCP clients

​
Claude Code

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

​
Codex

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

​
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:
  • launch_vars for stored environment-configuration names or IDs;
  • launch_arg_sets for stored ordered iOS argument-set names or IDs; and
  • launch_arguments for exact inline iOS argument tokens.
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; add 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: run remediation.command once in remediation.working_directory.
  • project_ambiguous: choose one remediation.candidate_roots value and retry with that exact project_dir.
  • project_invalid: repair remediation.config_path before retrying.
After one remediation, the agent retries start_dev_loop once. A second failure is reported instead of entering a setup loop. 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. Until the Marketplace plugin launches:
  1. Install the Revyl CLI in the Cloud environment setup.
  2. Include the project .cursor/mcp.json and revyl-mcp-dev-loop skill from the Cursor setup above.
  3. Add REVYL_API_KEY as a Runtime Secret.
  4. Start a new Cloud Agent so the MCP process receives the CLI and secret.
  5. Ask the agent to run the app with a remote build.
After the Marketplace plugin launches, its pinned runtime will replace the separate CLI installation. REVYL_API_KEY will still need to be configured as a Runtime Secret before starting a fresh Cloud Agent.

​
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:
The command copies REVYL_API_KEY from the current shell into the credential store, and the next MCP tool call picks it up without restarting the session. It reads an existing secret and cannot create one: if no key is present, add 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:
Run from the actual app root in a monorepo. If framework detection is wrong, rerun initialization with one explicit provider:
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.

​
Verify

Start a new agent chat and ask:
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).