# Rovela MCP server

> Connect Claude Code, Codex, Cursor, VS Code or Claude to Rovela stores. Server URL: https://mcp.rovela.ai/mcp (Streamable HTTP, OAuth 2.1). Human-readable page: https://rovela.ai/developers/mcp

## Introduction

The Rovela MCP server lets developers work on a Rovela store from their own AI tool: Claude Code, Codex, Cursor, VS Code or Claude. Your agent reads and edits the store's code, runs commands, queries its data, saves, and publishes, in the same editing workspace Rovela's builder uses, with a live preview.

The work runs on your own AI subscription and uses no Rovela credits. There is no repository to clone and nothing to set up on your computer: the store stays in Rovela, and your AI tool works on it through the server. What your tool reads (code, data) goes to your AI provider, as with any project you open in it.

**Server URL**

```bash
https://mcp.rovela.ai/mcp
```

It is a remote server (Streamable HTTP) with OAuth 2.1 sign-in, so any AI tool that supports remote MCP servers with OAuth can connect.

> Building with an AI assistant? This whole page is available as plain markdown at [rovela.ai/developers/mcp.md](/developers/mcp.md).

## Before you start

You need a Rovela account with developer access to at least one store. Developer access exists on stores owned by Rovela partner accounts: the owner always has it, and can turn it on for any admin of the store from its **Team** page.

Stores generated with Rovela are supported. Imported stores (connected from your own repository) are not available through the MCP server yet.

## Connect your AI tool

### Claude Code

Add Rovela:

```bash
claude mcp add --transport http rovela https://mcp.rovela.ai/mcp
```

Then type /mcp in Claude Code, pick rovela and sign in.

### Codex

Add Rovela:

```bash
codex mcp add rovela --url https://mcp.rovela.ai/mcp
```

Sign in:

```bash
codex mcp login rovela
```

### Cursor

Add to ~/.cursor/mcp.json, then select Connect in Cursor’s MCP settings:

```json
{
  "mcpServers": {
    "rovela": {
      "url": "https://mcp.rovela.ai/mcp"
    }
  }
}
```

### VS Code

Add to .vscode/mcp.json, then start the server and sign in:

```json
{
  "servers": {
    "rovela": {
      "type": "http",
      "url": "https://mcp.rovela.ai/mcp"
    }
  }
}
```

### Claude (web and desktop)

Settings → Connectors → Add custom connector, with this URL:

```
https://mcp.rovela.ai/mcp
```

### Other AI tools

Any tool that supports remote MCP servers with OAuth: add a remote (HTTP) server with the URL `https://mcp.rovela.ai/mcp`, then sign in when it asks.

## Sign-in and permissions

The first time your AI tool connects, it opens a Rovela sign-in page in your browser. You see which tool is asking and which of your stores it will reach, then choose its permissions:

| Permission | Lets your tool | On the sign-in page |
| --- | --- | --- |
| Read | List your stores, open a workspace, read and search code, query the database (read-only) | Always included |
| Edit and save | Write and edit files, run commands, save, propose a platform change | Ticked |
| Publish | Put a store live on its domain | Unticked |

A tool only sees the tools its permissions allow. To change them, sign in again from your AI tool and choose again; the new choice applies right away.

Your tool stays signed in and renews its access on its own. Signing out of a tool on one computer doesn't sign out the same tool on another. To end a tool's access everywhere, open your [Account](/account) page and select **Disconnect** under **Connected AI tools**: it stops working on its next call.

## How a session works

Your AI tool works on a store's **workspace**: a copy of the store running in the cloud, with a live preview that updates as files change. The server tells your tool how to use it, so a plain request like "add a Help link to the header and publish" is enough. Under the hood:

| Step | Tool | What happens |
| --- | --- | --- |
| 1 | `list_stores` | Finds the store and its `store_id`. |
| 2 | `open_store` | Starts the workspace (up to a minute) and returns the preview URL. |
| 3 | `read_file` | Reads the store's `CLAUDE.md` first: its conventions and the SDK reference. |
| 4 | `edit_file`, `write_file` | Changes the code. The preview updates live. |
| 5 | `run` | Checks the work, for example `npx tsc --noEmit`. |
| 6 | `save` | Keeps the work in the store's history without going live. |
| 7 | `publish` | Puts the store live, only when you ask. It takes 1 to 3 minutes. |

A workspace lasts up to 8 hours, and changes that aren't saved before it ends are lost, so your tool saves as it goes. Publishing closes the workspace; the next request opens a fresh one.

The store's owner may be working in Rovela at the same time. While Rovela's own builder is busy on a store, edits, commands, saves and publishes wait: your tool is told to retry in a minute.

## Tools

Each tool is listed only when the connection has its permission.

### Read (`stores:read`)

| Tool | What it does |
| --- | --- |
| `list_stores` | The stores you can work on, with their store_id, state, preview and live URLs. |
| `open_store` | Opens (or reuses) the store's editing workspace and returns its live preview URL. Call it before reading or editing files. It can take up to a minute: when it says it is still starting, call it again. |
| `store_status` | Workspace state, preview and live URLs, SDK version, and the progress of the last publish. |
| `read_file` | Reads a text file of the store. Paths are relative to the store root (e.g. app/page.tsx). Long files come in pages of lines. |
| `list_files` | Lists files and folders (folders end with /) under a store path; node_modules and build output are skipped. |
| `search` | Searches the store’s files for a pattern (extended regular expression, or exact text with fixed_strings). Returns file:line:text. |
| `db_query` | Runs one read-only SQL query (SELECT or WITH) on the store's LIVE database and returns up to 1,000 rows. |

### Edit and save (`stores:write`)

| Tool | What it does |
| --- | --- |
| `write_file` | Creates or replaces a text file of the store (folders are created). The preview updates live. Prefer edit_file to change part of a file. |
| `edit_file` | Replaces exact text in a store file: old_string must match the file exactly (whitespace included) and be unique unless replace_all is set. Read the file first. |
| `run` | Runs a shell command in the store folder (as the store's user) and returns its output, for example `npx tsc --noEmit` or `npm install some-package`. Stops after 45 seconds at most: start longer work in the background (`nohup … > /tmp/job.log 2>&1 &`) and read the log. Production builds and dev-server restarts are refused (they break the preview). |
| `save` | Saves the workspace (a commit in the store’s history) without going live. Save often: unsaved changes are lost when the workspace ends. |
| `propose_platform_change` | Sends a proposal for Rovela itself (the SDK, the store template, a reusable feature) to the Rovela team’s review queue. Partner accounts only. |

### Publish (`stores:publish`)

| Tool | What it does |
| --- | --- |
| `publish` | Puts the workspace live on the store’s domain (it saves first). Takes 1 to 3 minutes: if it is still running when this answers, follow it with store_status. Only when the user asks to publish. |

## Example prompts

Start your AI tool in an empty folder (the store lives in Rovela, not on your computer), then ask in plain words:

> What stores do I have? Open the first one, add a small Help link in the header that goes to the FAQ page, check it renders, then publish.

> On my store, find why the product page shows the wrong delivery estimate. Explain the cause before changing anything.

> Show me last month's ten largest orders on my store, with the customer and the total.

> Add a size guide to every product page, in every language the store uses, and save it without publishing.

## Safety and limits

> The database is the store's **live production database**. `db_query` is read-only, but commands your tool runs can write data. Turn on your AI tool's tool-approval setting to review calls before they run, and be careful when another MCP server feeds your tool content you don't control (prompt injection).

| Limit | Why |
| --- | --- |
| `.env` files and `.mcp.json` can't be read or written | They hold the store's secrets, which Rovela manages. |
| `CLAUDE.md`, `node_modules/`, `.next/`, `.git/`, `.claude/` and `.rovela/` can't be written | They are generated or managed by Rovela. |
| Binary files (images, fonts, videos) can't be written | Binaries break when the store is saved: upload them to the store's media and use their URL. |
| Files up to 2 MB | Larger files belong in the store's media. |
| `run` stops after 45 seconds | Start longer work in the background and read its log. |
| No production build, dev-server restart or `kill` | They take the live preview down. The real build runs when the store is published. |
| `db_query` returns up to 1,000 rows | Keeps answers within what an AI tool can read. |

If your company manages your network, ask IT to allow `mcp.rovela.ai` and `rovela.ai` (the sign-in page).

## Troubleshooting

| What you see | What to do |
| --- | --- |
| "This app isn't recognized" on the sign-in page | Your AI tool identifies itself in a way Rovela doesn't support yet. [Contact us](/contact) with the tool's name and version. |
| Signed in, but no stores are listed | You need developer access on a store: ask its owner to turn it on from the Team page. |
| "Rovela's builder is working on this store" | The owner is editing in Rovela right now. Wait a minute and try again. |
| "The workspace has ended" | Workspaces last up to 8 hours. Your tool calls `open_store` again; unsaved changes from the old one are lost. |
| "This store has no open workspace" after a publish | Publishing closes the workspace. Your tool opens a new one to keep working. |
| Codex can't sign in | Update Codex (`npm i -g @openai/codex`): older versions don't support MCP sign-in. |
| Your tool lost its connection | Sign in again from your AI tool (in Claude Code, `/mcp` → rovela → Authenticate). If it keeps happening, [contact us](/contact). |

## Changelog

- **2026-11-10: MCP server launched.** Developers can work on Rovela stores from Claude Code, Codex, Cursor, VS Code and Claude: 13 tools to open a store's workspace, read and edit its code, run commands, query its data, save and publish, with OAuth sign-in and three permissions.