> ## 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 MCP setup, including optional custom MCP with a literal command, lives in [MCP setup](/cli/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): ```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. Using Cursor Automations to prove CI-uploaded builds on a device? See [Cursor proof (BYO-CI)](/guides/cursor-proof). ## 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 # 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: ```bash theme={null} export REVYL_API_KEY=your-api-key ``` See [Authentication](/cli/authentication) for the full reference. ### 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. Pass the `session_id` each start returns to every later call. It targets exactly that device, even when parallel agents share one MCP server: ``` # Start both devices start_device_session(platform="android") → session_id: "" start_device_session(platform="ios") → session_id: "" # Install app on each install_app(app_url="https://example.com/app.apk", session_id="") install_app(app_url="https://example.com/app.ipa", session_id="") # Run the same flow on both device_tap(target="Sign In", session_id="") device_tap(target="Sign In", session_id="") device_type(target="Email field", text="user@test.com", session_id="") device_type(target="Email field", text="user@test.com", session_id="") # Verify both screenshot(session_id="") screenshot(session_id="") # Clean up each session stop_device_session(session_id="") stop_device_session(session_id="") ``` `session_index` (0, 1, ...) still works, but `session_id` is the safer choice when more than one agent or session is involved. See [MCP Tools Reference](/appendix/mcp-tool-ref#targeting-a-session). *** ## 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 test create login-smoke --from-session --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`) ```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 This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.