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

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

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

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

## Cursor

<Note>
  **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.
</Note>

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

```bash theme={null}
revyl auth login
revyl skill install --name revyl-mcp-dev-loop --cursor --force
```

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

```json theme={null}
{
  "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 theme={null}
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 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. download a missing or corrupt executable to a temporary file with a bounded
   timeout, verify it, install it atomically, and verify the cached file again;
5. 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; later
starts can use the verified cache. 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:

```bash theme={null}
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 --force
```

### Codex

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

```bash theme={null}
revyl auth login
codex mcp add revyl -- revyl mcp serve --profile dev
revyl skill install --name revyl-mcp-dev-loop --codex --force
```

## 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` or `auth_expired`: run `remediation.command`.
* `cloud_secret_required`: add `remediation.env_name` as a Runtime Secret and
  start a new Cloud session; do not retry when `restart_required` is true.
* `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.

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

## 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 theme={null}
revyl auth login
revyl init --non-interactive

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

# Native or Cloud flow using remote builders.
revyl dev --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 initialization with one explicit provider:

```bash theme={null}
revyl init --provider expo
revyl init --provider react-native
revyl init --provider swift
revyl init --provider android
```

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 theme={null}
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.