MCP Setup

Give your agent a supervised browser from Claude, Cursor, or VS Code. It navigates pages, clicks buttons, fills forms, and reads each page as an accessibility tree or a screenshot; you can watch live and take control at any point (see Supervised human handoff). No integration code required.

Install in Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "rove": {
      "command": "npx",
      "args": ["-y", "@roveapi/mcp"],
      "env": {
        "ROVE_API_KEY": "rvp_live_YOUR_KEY"
      }
    }
  }
}

Restart Claude Desktop. Rove tools will appear in the tool sidebar.

Don't have an API key yet? No problem — just omit the ROVE_API_KEY line. You can authenticate from inside your AI agent using the authenticate tool. See Zero-Key Onboarding below.

Install in Cursor

Add to your .cursor/mcp.json:

{
  "mcpServers": {
    "rove": {
      "command": "npx",
      "args": ["-y", "@roveapi/mcp"],
      "env": {
        "ROVE_API_KEY": "rvp_live_YOUR_KEY"
      }
    }
  }
}

Install in VS Code (Copilot)

Add to your VS Code settings.json:

{
  "github.copilot.chat.mcpServers": {
    "rove": {
      "command": "npx",
      "args": ["-y", "@roveapi/mcp"],
      "env": {
        "ROVE_API_KEY": "rvp_live_YOUR_KEY"
      }
    }
  }
}

Available Tools

Once installed, your agent has access to these tools:

Credit tools

Seven tools let an agent see prices and its balance and buy credits within the limits the account owner set (see Billing API for the owner setup). The stdio server (@roveapi/mcp 1.10.0 or later) and the hosted server expose the same definitions.

Each carries MCP tool annotations, with every hint set. They are hints a client may show; spending is limited by the owner's settings on the server, not by the client.

buy_credits is marked destructive because it can spend money: it may charge the owner's saved card. Clients that confirm destructive calls confirm it.

buy_credits without arguments never buys. It returns pricing, packs, top_ups (each pack's credits, price, item_id and, for a signed-in key, within_limits) and note, plus catalogue (the full catalogue), purchasing (whether this key may buy, and its limits) and how_to_buy.

buy_credits with item_id buys that pack and returns { purchase, idempotency_key, instruction }. instruction is one sentence saying what to do next, for example to give a payment link to the account owner and then call get_purchase. get_purchase and cancel_purchase return { purchase, instruction } too.

Derived idempotency. When idempotency_key is omitted, the server derives one from the key, the MCP session, item_id, payment and the current 10-minute window, and also checks the previous window. So the same call again in the same MCP session returns the first purchase (with replayed: true) for at least 10 and up to 20 minutes, and a retried call whose result was lost never buys twice. The hosted server's MCP session is its Mcp-Session-Id; the stdio server uses one session per process, so after restarting it pass the idempotency_key the first result returned to retry that purchase. To buy the same pack twice on purpose, pass a new idempotency_key each time.

Problems come back as tool errors (isError) whose text starts with the problem type and detail and carries retry, owner_action_url and the other members, then says what to do: retry with the same key, use a new key, or wait. A tool that runs out of credits (402 insufficient-credits, or a supervised session that ended credit_exhausted) ends its error with the next step: "Call get_credit_balance, then buy_credits with an item_id from top_ups." or "Ask the account owner to add credits at ...".

account_info keeps every field and adds purchasing_allowed (and the exact balance in millicredits).

Deprecation. The string price fields of buy_credits (packs, top_ups and note) and the buy_credits hint in account_info are deprecated in favour of catalogue and get_credit_catalogue. They are still returned, derived from the catalogue; removing them would need a new major version of @roveapi/mcp. packs is empty: the one-time packs it used to list are no longer sold.

Example Conversation

You: "Check what the checkout button says on https://example-store.com/product/123"

Agent: Calls navigate with the URL, then get_a11y_tree

"The checkout button says 'Add to Cart — $49.99'. The page also has a 'Buy Now' button and a quantity selector."

How It Works

The MCP server is a thin wrapper around the Rove REST API:

1. Agent decides to use a Rove tool
2. MCP server translates the tool call into a REST API request
3. API executes the action in a hosted Playwright browser
4. Result returns through MCP to the agent

Sessions are managed automatically — the MCP server creates a session on the first tool call and reuses it across the conversation.

Supervised human handoff

Supervised sessions require an rvp_live_ API key because test-mode keys use deterministic mock actions and do not allocate a streamable browser. Use authenticate first if you do not already have a live key. Opt in only for work on a site and account you own or are authorized to operate, and only when a brief interruption is safe; this is not a critical-workflow or recovery guarantee.

Use start_supervised_session, then let the agent navigate to that owned target. Call create_viewer_grant for the active supervised session and give its returned, session-bound viewer_url and one-time admission_code only to the intended human operator. The grant is bound to the hosted viewer's exact origin; treat the code as a short-lived secret and do not post it publicly or send target credentials through chat. Open the link to watch, then select Take control when ready. Human input is exclusive while control is held and agent input is fenced; select Return to agent for explicit handback.

After handback, the agent must obtain a successful fresh get_a11y_tree or screenshot observation before its next page mutation; stale observations are not enough to resume. End the session with the viewer's Stop session control or MCP close_session; closing releases the browser context and reports cleanup state. Do not use supervised browsing to bypass CAPTCHA, anti-bot protections, access controls, or a site's terms. If an interruption or safe cleanup cannot be confirmed, stop and handle the site through its normal owner-approved process instead.

Token Efficiency

The key advantage: get_a11y_tree returns a semantic representation of the page (~26K tokens) instead of a screenshot (~114K tokens). This means your agent can interact with web pages using 77% fewer tokens.

Zero-Key Onboarding

You can start using Rove without creating an API key first. Just install the MCP server without setting ROVE_API_KEY:

{
  "mcpServers": {
    "rove": {
      "command": "npx",
      "args": ["-y", "@roveapi/mcp"]
    }
  }
}

Then ask your agent to authenticate:

You: "Authenticate with Rove using my email [email protected]"

Agent: Calls authenticate with your email

The tool sends a magic link to your email. Click the link, and the agent automatically detects the activation — no copy-pasting tokens. You get 100 free credits on sign-up.

How credentials persist

After authentication, your API key is saved to ~/.config/rove/credentials.json. On future sessions, the MCP server loads this key automatically — you won't need to authenticate again.

If you later set a live ROVE_API_KEY environment variable, it takes precedence over saved credentials. A saved live key takes precedence over an environment test key so that a completed upgrade survives restarts.

Priority order: live ROVE_API_KEY env var → saved live key → test ROVE_API_KEY env var → other saved key → demo mode

Re-authentication

If you call authenticate with a configured live key, the tool returns "Already authenticated" without sending a new magic link. A configured test key starts the verified-email upgrade flow because test keys cannot use supervised streaming.

Troubleshooting

"Tool not found" — Restart your editor after adding the config. MCP servers load at startup.

"Invalid API key" — Check that ROVE_API_KEY is set correctly in the env block. Keys start with rvp_live_ or rvp_test_.

"Session expired" — Sessions expire after 30 minutes of inactivity. The MCP server creates a new one automatically.