> ## 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 Server > Connect Revyl to AI coding agents via MCP Connect Revyl to your AI coding tools so your agent can provision cloud devices, run tests, and interact with mobile apps directly. MCP gives capability. Skills give strategy. Your prompt gives intent. ## Quick Install **Cursor** -- add to `.cursor/mcp.json` in your project root (or `~/.cursor/mcp.json` for global): ```json theme={null} { "mcpServers": { "revyl": { "command": "revyl", "args": ["mcp", "serve"] } } } ``` Restart Cursor after saving. If you previously ran `revyl auth login`, no API key is needed. [![Install in VS Code](https://img.shields.io/badge/VS_Code-Revyl-0098FF?style=flat\&logo=visualstudiocode\&logoColor=ffffff)](vscode:mcp/install?%7B%22name%22%3A%22revyl%22%2C%22type%22%3A%22stdio%22%2C%22command%22%3A%22revyl%22%2C%22args%22%3A%5B%22mcp%22%2C%22serve%22%5D%7D) [![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Revyl-24bfa5?style=flat\&logo=visualstudiocode\&logoColor=ffffff)](vscode-insiders:mcp/install?%7B%22name%22%3A%22revyl%22%2C%22type%22%3A%22stdio%22%2C%22command%22%3A%22revyl%22%2C%22args%22%3A%5B%22mcp%22%2C%22serve%22%5D%7D) **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. ## Prerequisites ### 1. Install the CLI ```bash theme={null} 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 ```bash theme={null} revyl auth login # Browser-based login ``` Or set an API key: ```bash theme={null} export REVYL_API_KEY=your-api-key ``` ### 3. Verify ```bash theme={null} 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): ```json theme={null} { "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 ```bash theme={null} 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: ```bash theme={null} codex mcp add revyl -- revyl mcp serve ``` Config file (`~/.codex/config.toml`): ```toml theme={null} [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` ```json theme={null} { "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`: ```json theme={null} { "mcp": { "servers": { "revyl": { "command": "revyl", "args": ["mcp", "serve"], "env": { "REVYL_API_KEY": "your-api-key" } } } } } ``` ### Windsurf Create or edit `~/.codeium/windsurf/mcp_config.json`: ```json theme={null} { "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="user@test.com", session_index=0) device_type(target="Email field", text="user@test.com", 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`) ```text theme={null} 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 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`) ```text theme={null} 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`) ```text theme={null} 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`) ```text theme={null} 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 The CLI is not in your PATH. ```bash theme={null} 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" ``` ```bash theme={null} revyl auth login # Re-authenticate revyl auth status # Check current status ``` 1. Restart your IDE/tool 2. Check the server starts manually: `revyl mcp serve` 3. Enable debug logging by adding `"--debug"` to the `args` array in your MCP config 4. Run `revyl device doctor` to check connectivity Sessions auto-terminate after 5 minutes of idle time. Call `start_device_session` to provision a new device. 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: 1. Run `device_doctor` to verify session and device status 2. Confirm the session still appears in `list_device_sessions` 3. Start a fresh session if the current one was terminated externally 1. Take a `screenshot()` to see what's actually on screen 2. Use more specific descriptions: `"blue 'Sign In' button"` instead of `"button"` 3. Rephrase the target using exact visible text and retry