MCP Server

MCP setup, including optional custom MCP with a literal command, lives in MCP setup. This page is a short client-index only.

Quick Install

Cursor — add to .cursor/mcp.json in your project root (or ~/.cursor/mcp.json for global):

{
  "mcpServers": {
    "revyl": {
      "command": "revyl",
      "args": ["mcp", "serve"]
    }
  }
}

Restart Cursor after saving. If you previously ran revyl auth login, no API key is needed. Claude Code: claude mcp add revyl -- revyl mcp serve Codex: codex mcp add revyl -- revyl mcp serve

The one-click buttons install the server without an API key. Run revyl auth login first, or add REVYL_API_KEY to your MCP config afterward.

Using Cursor Automations to prove CI-uploaded builds on a device? See Cursor proof (BYO-CI).

Prerequisites

1. Install the CLI

curl -fsSL https://revyl.com/install.sh | sh
brew install RevylAI/tap/revyl    # Homebrew (macOS)
pipx install revyl                # pipx (cross-platform)
uv tool install revyl             # uv
pip install revyl                 # pip

2. Authenticate

revyl auth login                  # Prints an approval URL to open in any browser

Approval happens through Revyl rather than a local port, so this works over SSH, in a container, and in a cloud agent. Or set an API key for an unattended machine:

export REVYL_API_KEY=your-api-key

See Authentication for the full reference.

3. Verify

revyl auth status   # Should show "Authenticated"
revyl mcp serve     # Should start the MCP server (Ctrl+C to stop)

Setup by Tool

Cursor

Create .cursor/mcp.json in your project root (project-scoped) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "revyl": {
      "command": "revyl",
      "args": ["mcp", "serve"],
      "env": {
        "REVYL_API_KEY": "your-api-key"
      }
    }
  }
}

Restart Cursor after editing. If you previously ran revyl auth login, you can omit the env block.

Claude Code

claude mcp add revyl -- revyl mcp serve
claude mcp add revyl -e REVYL_API_KEY=your-api-key -- revyl mcp serve  # Explicit key
claude mcp list  # Verify

Codex (OpenAI)

CLI:

codex mcp add revyl -- revyl mcp serve

Config file (~/.codex/config.toml):

[mcp_servers.revyl]
command = "revyl"
args = ["mcp", "serve"]
env = { REVYL_API_KEY = "your-api-key" }

Keep MCP and your shell CLI pointed at the same binary. A mismatch can make session lists appear inconsistent.

Claude Desktop

Edit the config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "revyl": {
      "command": "revyl",
      "args": ["mcp", "serve"],
      "env": {
        "REVYL_API_KEY": "your-api-key"
      }
    }
  }
}

VS Code (Copilot Chat)

Add to your VS Code settings.json:

{
  "mcp": {
    "servers": {
      "revyl": {
        "command": "revyl",
        "args": ["mcp", "serve"],
        "env": {
          "REVYL_API_KEY": "your-api-key"
        }
      }
    }
  }
}

Windsurf

Create or edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "revyl": {
      "command": "revyl",
      "args": ["mcp", "serve"],
      "env": {
        "REVYL_API_KEY": "your-api-key"
      }
    }
  }
}

Multi-Session Example

Run the same login flow on iOS and Android simultaneously:

# Start both devices
start_device_session(platform="android")   → session_index: 0
start_device_session(platform="ios")       → session_index: 1

# Install app on each
install_app(app_url="https://example.com/app.apk", session_index=0)
install_app(app_url="https://example.com/app.ipa", session_index=1)

# Run the same flow on both
device_tap(target="Sign In", session_index=0)
device_tap(target="Sign In", session_index=1)

device_type(target="Email field", text="[email protected]", session_index=0)
device_type(target="Email field", text="[email protected]", session_index=1)

# Verify both
screenshot(session_index=0)
screenshot(session_index=1)

# Clean up
stop_device_session(all=true)

Prompt Library

Use these copy/paste prompts to activate the right skill family.

CLI dev-loop prompt (`revyl-cli-dev-loop`)

Use the revyl-cli-dev-loop skill.
Goal: verify I can sign in and reach Home using CLI flow.
Use only Revyl CLI commands (no MCP tool calls).

Steps:
1) start from project root
2) run revyl init if needed
3) run revyl dev and wait for readiness
4) summarize exact actions I should perform in app
5) convert successful flow into a test:
   - revyl test create login-smoke --from-session <session-id> --platform ios
   - revyl test open login-smoke
   - revyl test push login-smoke --force
   - revyl test run login-smoke
6) if run fails, fetch report with revyl test report login-smoke --json and classify failure

MCP dev-loop prompt (`revyl-mcp-dev-loop`)

Use the revyl-mcp-dev-loop skill.
Use Revyl MCP tools only.
Goal: bypass login and land on Home screen.

Rules:
1) first call must be start_dev_loop
2) loop: screenshot -> one-line observation -> one best action -> screenshot verify
3) max 2 actions before re-anchor
4) if state is unexpected, stop and re-anchor
5) end with summary: final screen, actions, anomalies

MCP create prompt (`revyl-mcp-create`)

Use the revyl-mcp-create skill.
Create a new ios test named checkout-smoke from this flow:
- open Shop
- open product Orchid Mantis
- add to cart
- open cart
- verify Orchid Mantis and price $62.00

Use MCP tools to:
1) validate YAML
2) create/update test
3) run test
4) report pass/fail with task id

CLI analyze prompt (`revyl-cli-analyze`)

Use the revyl-cli-analyze skill.
Analyze this failed test run end-to-end:
1) run revyl test report checkout-smoke --json
2) classify failure as REAL BUG, FLAKY TEST, INFRA ISSUE, or TEST IMPROVEMENT
3) provide exact next action and rerun command

Verify It Works

After configuring your tool, try these prompts:

“Start an Android device and take a screenshot”
“List all my Revyl tests”
“Run the login-flow test”
“Install this app and tap the Sign In button”

If something goes wrong, ask the agent to “Run device_doctor” — it checks auth, session, device, and grounding health.

Troubleshooting

"revyl: command not found"

The CLI is not in your PATH.

which revyl        # Check location
pip show revyl     # If installed via pip

# Or use the full path in your MCP config:
# "command": "/usr/local/bin/revyl"

Authentication errors

revyl auth login     # Re-authenticate
revyl auth status    # Check current status

MCP server not responding

Restart your IDE/tool
Check the server starts manually: revyl mcp serve
Enable debug logging by adding "--debug" to the args array in your MCP config
Run revyl device doctor to check connectivity

"no active device session"

Sessions auto-terminate after 5 minutes of idle time. Call start_device_session to provision a new device.

DNS failures in sandboxed agents

If direct device service DNS lookups fail (e.g. in Codex/Claude sandbox environments), the CLI/MCP automatically falls back to backend proxy routing.If actions still fail after fallback:

Run device_doctor to verify session and device status
Confirm the session still appears in list_device_sessions
Start a fresh session if the current one was terminated externally

Grounding model not finding elements

Take a screenshot() to see what’s actually on screen
Use more specific descriptions: "blue 'Sign In' button" instead of "button"
Rephrase the target using exact visible text and retry

Getting Started

CLI

Builds

Tests

Develop

Atlas

Integrations

Appendix

Quick Install

Prerequisites

1. Install the CLI

2. Authenticate

3. Verify

Setup by Tool

Cursor

Claude Code

Codex (OpenAI)

Claude Desktop

VS Code (Copilot Chat)

Windsurf

Multi-Session Example

Prompt Library

CLI dev-loop prompt (`revyl-cli-dev-loop`)

MCP dev-loop prompt (`revyl-mcp-dev-loop`)

MCP create prompt (`revyl-mcp-create`)

CLI analyze prompt (`revyl-cli-analyze`)

Verify It Works

Troubleshooting

​Quick Install

​Prerequisites

​1. Install the CLI

​2. Authenticate

​3. Verify

​Setup by Tool

​Cursor

​Claude Code

​Codex (OpenAI)

​Claude Desktop

​VS Code (Copilot Chat)

​Windsurf

​Multi-Session Example

​Prompt Library

​CLI dev-loop prompt (revyl-cli-dev-loop)

​MCP dev-loop prompt (revyl-mcp-dev-loop)

​MCP create prompt (revyl-mcp-create)

​CLI analyze prompt (revyl-cli-analyze)

​Verify It Works

​Troubleshooting

Quick Install

Prerequisites

1. Install the CLI

2. Authenticate

3. Verify

Setup by Tool

Cursor

Claude Code

Codex (OpenAI)

Claude Desktop

VS Code (Copilot Chat)

Windsurf

Multi-Session Example

Prompt Library

CLI dev-loop prompt (`revyl-cli-dev-loop`)

MCP dev-loop prompt (`revyl-mcp-dev-loop`)

MCP create prompt (`revyl-mcp-create`)

CLI analyze prompt (`revyl-cli-analyze`)

Verify It Works

Troubleshooting