MCP Server Setup - Revyl Documentation

The Revyl MCP server lets AI coding agents provision cloud devices, run tests, and interact with mobile apps directly from your IDE. This guide covers setup for every major AI tool.

Quick Install

Add to Cursor

If the button does not open Cursor, go to Settings > MCP > Add and add server revyl with args mcp, serve.

Claude Code: claude mcp add revyl -- revyl mcp serve Codex: codex mcp add revyl -- revyl mcp serve

The one-click buttons install the MCP server without an API key. Run revyl auth login first, or add REVYL_API_KEY to your MCP config afterward. See the manual setup sections below for full config with env vars.

Prerequisites

1. Install the CLI

brew install RevylAI/tap/revyl

2. Authenticate

Either log in interactively (stores credentials locally):

revyl auth login

Or get your API key from the Revyl dashboard and pass it via environment variable:

export REVYL_API_KEY=your-api-key

3. Verify

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

Setup by Tool

Every tool uses the same core config: the command revyl with args ["mcp", "serve"]. The only difference is where each tool expects the config file.

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

One command:

claude mcp add revyl -- revyl mcp serve

With an explicit API key:

claude mcp add revyl -e REVYL_API_KEY=your-api-key -- revyl mcp serve

Verify: claude mcp list

Codex (OpenAI)

codex mcp add revyl -- revyl mcp serve

Claude Desktop

Edit the config file for your OS:

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"
      }
    }
  }
}

Restart Claude Desktop after saving.

VS Code (Copilot Chat)

Add to your VS Code settings.json (Cmd+Shift+P > “Preferences: Open User 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"
      }
    }
  }
}

Installing Agent Skills (Recommended)

The Revyl agent skill teaches your AI assistant optimal workflows, grounding patterns, and troubleshooting steps. It’s optional but significantly improves the experience.

Revyl ships embedded skill families and can install them with a single command. No network access or extra downloads required.

Default install

revyl skill install

This auto-detects which AI tools you have installed (Cursor, Claude Code, Codex) and installs the CLI skill family by default:

revyl-cli
revyl-cli-create
revyl-cli-analyze
revyl-cli-dev-loop

Install MCP family instead:

revyl skill install --mcp

Install both families:

revyl skill install --cli --mcp

Tool-specific install

revyl skill install --cursor

By default, skills are installed at the project level. Use --global to install to your user-level directory instead:

revyl skill install --cursor --global

Installation locations

Tool	Project-level	User-level (`--global`)
Cursor	`.cursor/skills/<skill-name>/SKILL.md`	`~/.cursor/skills/<skill-name>/SKILL.md`
Claude Code	`.claude/skills/<skill-name>/SKILL.md`	`~/.claude/skills/<skill-name>/SKILL.md`
Codex	`.codex/skills/<skill-name>/SKILL.md`	`~/.codex/skills/<skill-name>/SKILL.md`

Can I use multiple skills?

Yes. Skills are folder-based, so you can keep the Revyl skill and add your own team skills side by side. Example (Codex):

.codex/skills/
  revyl-cli-dev-loop/
    SKILL.md
  revyl-mcp-dev-loop/
    SKILL.md
  my-team-bug-triage/
    SKILL.md
  my-team-release-checklist/
    SKILL.md

Use the revyl-cli*/revyl-mcp* skills as your base capability and add scenario-specific team skills on top.

Other skill commands

revyl skill list                                 # List available skills
revyl skill show --name revyl-cli-dev-loop       # Print a specific skill
revyl skill export --name revyl-mcp-dev-loop -o SKILL.md
revyl skill revyl-mcp-dev-loop install --codex   # Shortcut install form
revyl skill install --force      # Overwrite an existing installation

After installing, the skill is automatically discovered by your AI agent on startup. Restart your IDE if it was already running.

Verify It Works

After setup, try these prompts with your AI agent:

“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”

Then try a loop-oriented prompt:

Use Revyl MCP tools only.
Goal: bypass login and reach the home screen.
For each step: screenshot, describe what is visible in one short line, take one best action, screenshot to verify, then continue.
If a step fails, re-observe before acting again.

If the agent starts taking blind actions, re-anchor it:

Pause actions. Re-anchor now:
1) screenshot,
2) describe state,
3) take one action with reason,
4) screenshot verify.
Then continue.

If you want strict execution-first behavior for dev loop sessions, use this prompt:

Use Revyl MCP tools only.
Primary objective: start dev loop first, then act only from observed screen state.

Hard rules:
1) First tool call must be start_dev_loop.
2) Do not call list_tests/list_remote_tests/list_variables/list_env_vars unless I explicitly ask.
3) Loop: screenshot -> one-line observation -> one best action -> screenshot verify.
4) Max 2 actions in a short burst, then re-anchor with screenshot.
5) If screen state is unexpected, stop and re-anchor before continuing.

For a full set of copy/paste templates, see the Agent Prompt Pack.

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

Example Prompt Library

Use these copy/paste prompts to activate the correct 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 --hotreload 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 dev test create login-smoke --platform ios
   - revyl dev 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

Available MCP Tools

The Revyl MCP server exposes tools across several categories:

Category	Tools
Device Session	`start_device_session`, `stop_device_session`, `get_session_info`
Device Actions	`device_tap`, `device_double_tap`, `device_long_press`, `device_type`, `device_swipe`, `device_drag`
Vision	`screenshot`
App Management	`install_app`, `launch_app`
Test Management	`run_test`, `run_workflow`, `list_tests`, `create_test`
Diagnostics	`device_doctor`

Device action tools are grounded by default — describe the element in natural language (e.g. target="Sign In button") and coordinates are auto-resolved via AI vision. You can also pass raw x, y coordinates as an override.

Troubleshooting

”revyl: command not found”

The CLI is not in your PATH.

# Check where it's installed
which revyl        # npm
pip show revyl     # 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
Test manually: revyl mcp serve
Enable debug logging: add "REVYL_DEBUG": "true" to your config’s env block
Run revyl device doctor to check connectivity

”no active device session”

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

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

Next Steps

Agent Prompt Pack

Copy/paste prompts for reliable screenshot-observe-action loops and ad hoc-to-test conversion.

Agent Journeys

End-to-end playbooks for dev loop and ad hoc-to-test workflows.

CLI Reference

Full command reference for the Revyl CLI.

Quick Start

Get up and running with Revyl in 5 minutes.

API Reference

REST API documentation for programmatic access.

Integrations

GitHub, Slack, Expo, and more.

Getting Started

Tests

Builds

Workflows

Monitoring

Integrations

CLI

CI/CD

Device Automation

​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

​Installing Agent Skills (Recommended)

​Default install

​Tool-specific install

​Installation locations

​Can I use multiple skills?

​Other skill commands

​Verify It Works

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

​Available MCP Tools

​Troubleshooting

​”revyl: command not found”

​Authentication errors

​MCP server not responding

​”no active device session”

​Grounding model not finding elements

​Next Steps

Agent Prompt Pack

Agent Journeys

CLI Reference

Quick Start

API Reference

Integrations

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

Installing Agent Skills (Recommended)

Default install

Tool-specific install

Installation locations

Can I use multiple skills?

Other skill commands

Verify It Works

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

Available MCP Tools

Troubleshooting

”revyl: command not found”

Authentication errors

MCP server not responding

”no active device session”

Grounding model not finding elements

Next Steps