# MCP Integration

Source: https://docs.rooquiz.com/en/integrations/mcp

> RooQuiz ships an MCP server so ChatGPT, Claude, Cursor, Codex and other AI clients can work in your team with natural language — build quizzes, manage translations, work leads, read bookings and stats.

RooQuiz ships an **MCP (Model Context Protocol) server** that lets AI clients — ChatGPT, claude.ai, Claude Desktop, Claude Code, Cursor, Codex, and others — work inside your team. With natural language you can create quizzes from templates or from scratch, append and edit questions, configure report dimensions or outcome types, change delivery settings and get share links, manage translations and respondents, work your leads, and read bookings, submission records, stats and conversion funnels — instead of doing everything by hand in the editor.

<Callout type="info">
  RooQuiz has no built-in AI quiz generator. To build a quiz with AI, connect **your own AI client** over MCP and ask it to — it uses the tools below, and you review the result in the editor.
</Callout>

<Callout type="info">
  MCP is a feature for **power users** — you'll need an AI client that supports MCP. For basic, visual quiz building we still recommend the [editor](https://docs.rooquiz.com/en/editor).
</Callout>

## How it works

* An AI client connects to RooQuiz's MCP endpoint (`/api/mcp`) using one of two auth methods: **OAuth authorization** (recommended — supported clients just sign in via the browser) or a **personal API token**.
* Either way, the AI acts **as you** within the currently active team.
* Every action goes through the same **access checks** as the admin UI; write operations are also recorded in the **audit log**.
* So what the AI can do is bounded entirely by your role and permissions in that team — it can't exceed them.

## Option 1: OAuth authorization (recommended)

Clients that support MCP OAuth — ChatGPT, claude.ai and Claude Code — **need no manually created token**. Just provide the endpoint URL: the client discovers the authorization server automatically and opens your browser, where you sign in to RooQuiz, pick the team to authorize, and click "Authorize".

<Tabs items="['ChatGPT', 'claude.ai (Web)', 'Claude Code']">
  <Tab value="ChatGPT">
    RooQuiz is available as an app in ChatGPT. Click **Use in ChatGPT** at the top of the RooQuiz admin to open it, then connect — your browser is redirected to the RooQuiz authorization page; sign in, pick a team, and click "Authorize".
  </Tab>

  <Tab value="claude.ai (Web)">
    Open claude.ai's **Settings → Connectors → Add custom connector**:

    1. Name it anything (e.g. `RooQuiz`).
    2. Use your endpoint (looks like `https://your-domain/api/mcp`) as the remote MCP server URL.
    3. Save and click "Connect" — your browser is redirected to the RooQuiz authorization page; sign in, pick a team, and click "Authorize".
  </Tab>

  <Tab value="Claude Code">
    Run anywhere in your terminal (**without** a token header):

    ```bash
    claude mcp add --transport http rooquiz https://your-domain/api/mcp
    ```

    The first time you connect in Claude Code (e.g. `/mcp`), your browser opens automatically to complete authorization.
  </Tab>
</Tabs>

About OAuth connections:

* The team you pick during authorization becomes the initially active team; the AI can still switch later via `switch_active_tenant`.
* The connection shows up in the token list under **Settings → MCP Integration** (tagged **OAuth**); **revoking it disconnects** that client. It does **not** count toward the 5-token limit.
* Credentials renew automatically (the access token refreshes on a 1-hour rolling basis; the connection itself stays valid for 30 days and extends with use) — nothing to maintain by hand.

## Option 2: Personal token (PAT)

For clients without OAuth support (Cursor, Codex CLI, Claude Desktop) or browserless environments like CI, connect with a personal API token.

### Create a token

Go to **Settings → MCP Integration** and click **Create token**:

1. Give it a **Token name** (for recognition, e.g. `Cursor - my Mac`).
2. Pick an **Initial team** — the token operates on this team by default, and the AI can later switch to any other team you belong to via the `switch_active_tenant` tool.
3. After creation, a plaintext token starting with `rqp_live_` is shown.

<Callout type="warning">
  **The plaintext token is shown only once.** It cannot be retrieved after you leave the page. Copy it immediately; if lost, you must revoke it and create a new one.
</Callout>

Limits:

* Each user can hold at most **5 tokens** (including revoked ones; OAuth connections don't count). To create more, **delete** one to free a slot ("revoke" only deactivates — it does not free the slot). A revoked personal token can be switched back on with **Enable**.
* A token is a **personal credential** — never commit it to source control or share it publicly.

### Configure your AI client

On the **Settings → MCP Integration** page you can copy ready-made config snippets for each client, along with your **Endpoint URL** (looks like `https://your-domain/api/mcp`). Replace `rqp_live_xxx...` in the snippet with the token you just generated.

<Tabs items="['Claude Code (CI)', 'Cursor', 'Codex CLI', 'Claude Desktop']">
  <Tab value="Claude Code (CI)">
    For Claude Code, prefer the OAuth flow above; a token header is only needed in browserless environments like CI:

    ```bash
    claude mcp add --transport http rooquiz https://your-domain/api/mcp \
      --header "Authorization: Bearer rqp_live_xxx..."
    ```
  </Tab>

  <Tab value="Cursor">
    Native HTTP MCP support. Write to project-level `.cursor/mcp.json` or global `~/.cursor/mcp.json`:

    ```json
    {
      "mcpServers": {
        "rooquiz": {
          "url": "https://your-domain/api/mcp",
          "headers": { "Authorization": "Bearer rqp_live_xxx..." }
        }
      }
    }
    ```
  </Tab>

  <Tab value="Codex CLI">
    Native HTTP MCP support. Write to `~/.codex/config.toml`:

    ```toml
    [mcp_servers.rooquiz]
    url = "https://your-domain/api/mcp"
    bearer_token_env_var = "ROOQUIZ_MCP_TOKEN"
    ```

    For security Codex only accepts an **env var name**, not an inline plaintext token. Also export it in your shell:

    ```bash
    export ROOQUIZ_MCP_TOKEN="rqp_live_xxx..."
    ```
  </Tab>

  <Tab value="Claude Desktop">
    Claude Desktop only speaks stdio natively, so HTTP MCP requires the `mcp-remote` bridge (auto-downloaded on first use; needs local Node ≥ 18). Paste into the config file, then **restart** Claude Desktop:

    * macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
    * Windows: `%APPDATA%\Claude\claude_desktop_config.json`

    ```json
    {
      "mcpServers": {
        "rooquiz": {
          "command": "npx",
          "args": [
            "-y", "mcp-remote",
            "https://your-domain/api/mcp",
            "--header", "Authorization: Bearer rqp_live_xxx..."
          ]
        }
      }
    }
    ```
  </Tab>
</Tabs>

## Example prompts

Once your client is connected, talk to it in plain language. Each of these exercises a
different part of the server:

**Build from a template**

> Show me the coaching templates, create a scored quiz from the readiness one, then add two
> questions about budget.

Exercises `list_templates` → `create_form_from_template` → `add_question`.

**Work the leads**

> List the leads my Wheel of Life quiz captured this week, tag everyone who scored under 40
> as follow-up, and assign them to me.

Exercises `list_leads` → `set_lead_tags` → `assign_leads`.

**Diagnose the funnel**

> Which of my quizzes has the worst completion rate, and where exactly do people drop off?

Exercises `list_forms` → `get_form_stats` → `get_form_funnel`.

**Go multilingual**

> Translate my promotion-readiness quiz into Spanish and German, keeping the question codes.

Exercises `list_form_translations` → `create_form_translation`.

<Callout type="info">
  Respondent names, email addresses and phone numbers come back **masked**
  (`j***g@example.com`). Masking is irreversible, so refer to a respondent by id rather than
  pasting a masked value back into a prompt.
</Callout>

## Available tools

Once connected, the AI assistant can call the 44 tools below. They all act on the team the token is **currently active** in.

### Team (Tenant)

| Tool                   | What it does                                                                                                                                                                                                             |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `list_my_tenants`      | List all teams you belong to, marking the currently active one.                                                                                                                                                          |
| `get_active_tenant`    | Return the team the token is currently active in (including its team address); all writes default to it.                                                                                                                 |
| `switch_active_tenant` | Switch the active team (persists across sessions; target must be a team you've joined).                                                                                                                                  |
| `invite_member`        | Invite someone to the active team by email as member or admin; an invitation email with a join link is sent. Owner / admin only.                                                                                         |
| `update_tenant_slug`   | Change the team address — the first path segment of every quiz link on the platform domain. Owner / admin only. Every public quiz link moves at once and the old address stops working; `/a/<token>` links keep working. |

### Templates

| Tool                        | What it does                                                                                                                                                                                          |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list_templates`            | List the active templates in the public template library (title, scene, description, category, usage count), most-used first.                                                                         |
| `create_form_from_template` | Create a new quiz from a template in one call: structure, scoring / report configuration, visual settings and all language versions. The fastest way to build a quiz when a suitable template exists. |

### Form

| Tool             | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `create_form`    | Create a quiz (`knowledge_quiz`, `scored_quiz`, or `outcome_quiz` typing quiz). Can take a questions array and report config in one call to avoid round trips. An outcome quiz **must** include `report.outcomes` (the list of result types) at creation, with every choice voting for types via `outcomes`.                                                                                                                                                             |
| `list_forms`     | List the current team's quizzes, newest first, without question content.                                                                                                                                                                                                                                                                                                                                                                                                 |
| `get_form`       | View a quiz's full details (the `fields[]` question list, report config, etc.); call this first to get each question's `code` before editing — for outcome quizzes, the result-type `code`s live in `report.outcomeAnalysis.outcomes`.                                                                                                                                                                                                                                   |
| `update_form`    | Update title, description, open/closed state, covers (`flagImg` / `landingImage`), theme, social share card (`openGraph`), system text, or merge-replace the `report` config by sub-key; for outcome quizzes, pass `report.outcomes` to merge-update result types by `code` (configured images are kept, and removing a type still referenced by question votes is rejected). **Language** can be changed only while the quiz has no language versions; **scene** never. |
| `delete_form`    | Move a quiz to the trash (soft delete): hidden from `list_forms`, recoverable for 5 days via `restore_form` (then permanently purged). Any team member can delete; submission records are kept until permanent purge.                                                                                                                                                                                                                                                    |
| `restore_form`   | Restore a quiz deleted by `delete_form` from the trash.                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `duplicate_form` | Duplicate a quiz: clones its question structure, scoring, report, visuals and settings plus **all language translations** into a new quiz owned by you (with fresh links). Does **not** copy submission records, integrations or ban state. Optional `newTitle`.                                                                                                                                                                                                         |

### Sharing & delivery settings

| Tool                   | What it does                                                                                                                                                                                                                                                                                                                                               |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `get_form_share_info`  | Everything needed to publish a quiz: the public answer link (also per language version), the team's custom domain and whether it is serving, embed snippets in three modes (inline / popup / iframe), and the current delivery settings. Pass `utmSource` to tag every link and snippet for one channel.                                                   |
| `update_form_settings` | Change how a quiz is delivered: who may answer and whether the report needs an email (the lead-capture gate) and a verification code, time limit (knowledge quizzes), sharing and share card, answer sheet, crowd comparison, the result-page booking section and its Cal.com link, the feedback block, PDF download (Pro), Google Analytics ID, and more. |

### Question

| Tool              | What it does                                                                                                                                                                                                                                                                                                                                                                                                             |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `add_question`    | Append an item to the end: a question, a page break (`Breaker`), or a display block (`Statement` rich-text passage, `Swiper` image carousel). Question types: SingleCheck / MultiCheck / TrueFalse, FillBlank, DropDown, Ordering (knowledge quiz), NumberField and Rate (scored quiz). In an outcome quiz, every choice must declare which result types it votes for (TrueFalse uses `trueOutcomes` / `falseOutcomes`). |
| `insert_question` | Insert an item at a specific position, using `after` / `before` to reference an existing `code`.                                                                                                                                                                                                                                                                                                                         |
| `move_question`   | Move an existing question or page break to a new position by `code`.                                                                                                                                                                                                                                                                                                                                                     |
| `update_question` | Update a question by `code`: stem, note, explanation, required flag, score, correct answer, FillBlank AI grading, number / date / rating options, or **replace all choices** of a choice question. Display blocks are edited here too. **Cannot change the question type.**                                                                                                                                         |
| `delete_question` | Delete a question or page break by `code`.                                                                                                                                                                                                                                                                                                                                                                               |

### Report dimensions

| Tool                     | What it does                                                                                                                                                                                                                                                                                                                                          |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `set_dimension_analysis` | Set a quiz's multi-dimension analysis (radar chart dimensions) as a whole; only `scored_quiz` has dimensions, and each uses a formula over question `code`s (knowledge quizzes have no dimensions). Pass an empty array to clear. Not applicable to outcome quizzes (they have no dimensions — configure result types via `report.outcomes` instead). |

### Translations (FormTranslation)

Offer a quiz in multiple languages: one source quiz (primary language) plus one translation per other language (same structure as the source, only the text is translated; submission records always anchor to the source quiz).

| Tool                      | What it does                                                                                                                                                                                                                               |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `create_form_translation` | Add a language version to a quiz, cloning the source copy as the initial draft (same `code`s, source-language text), and return that content to translate right away. The language must differ from the primary, at most one per language. |
| `list_form_translations`  | List a quiz's existing language versions (language, active flag, public link, etc.).                                                                                                                                                       |
| `get_form_translation`    | Read one language version's full content (including `fields[]` and `report`) to translate in place — every `code` must stay identical to the source.                                                                                       |
| `update_form_translation` | Save a language version's translated copy (title / description / fields / report / systemText), or pause it via `isActive`; the structure is fixed by the source, you only change text, and omitted fields count as partial translation.   |
| `delete_form_translation` | Delete one language version.                                                                                                                                                                                                               |

### Respondents (examinees)

The people who take a quiz — called Respondents in the admin UI; the tools keep the examinee wording. Each examinee is bound to a single team; the tools return safe fields only — password, verification code, reset token and other sensitive fields are **never** exposed.

| Tool              | What it does                                                                                                                                                                                            |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list_examinees`  | List the current team's respondents, with optional fuzzy search by email / name and status (active / disabled) filtering.                                                                               |
| `get_examinee`    | View a respondent's detail (including custom `customData`) by its business ID `examineeId` (e.g. `AB1234567890`, shown in the list).                                                                    |
| `update_examinee` | Edit a respondent's name / status / customData by `examineeId` (customData is validated against the team's field definitions and replaces the whole object). **Email and team cannot be changed.** |

### Leads

| Tool                 | What it does                                                                                                                                                                                                                    |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list_leads`         | List the team's leads — one per respondent across all quizzes, with follow-up status, assignee, colour tags, submission count and next booking. Filter by status / assignee / tags / created date / keyword / upcoming booking. |
| `get_lead`           | View one lead by `leadId`, optionally with the respondent's submission history, the team's internal comments, and the change timeline.                                                                                          |
| `list_lead_settings` | Read the team's follow-up statuses, tag library and assignable members. Call this before writing — status codes, tag codes and member ids are team-specific.                                                                    |
| `update_lead`        | Move one lead to another follow-up status (e.g. new → contacted); recorded on the lead's timeline.                                                                                                                              |
| `assign_leads`       | Assign up to 50 leads to an active member in one call (`"me"` for yourself), or clear the assignee. The assignee gets one aggregated notification.                                                                              |
| `set_lead_tags`      | Set colour tags on up to 50 leads in one call: `replace` (single lead), or `add` / `remove` for batches so other people's tags survive.                                                                                         |
| `add_lead_comment`   | Write an internal follow-up comment on a lead (team-only, never shown to the respondent), optionally tied to one submission.                                                                                                    |

### Bookings

| Tool            | What it does                                                                                                                                                                                                                                               |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list_bookings` | List the team's bookings synced from Cal.com, earliest first, with time, status, Cal.com event type, attendee, source quiz and submission, and lead owner. Filter by status / quiz / respondent / time range. Read-only — bookings are changed in Cal.com. |

### Records & Analytics

Read quiz performance and submissions so the AI can close the build → measure → iterate loop.

| Tool              | What it does                                                                                                                                                                            |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `get_form_stats`  | Read a quiz's stats over the last N days (default 30, max 180): KPI overview, daily trend, channels (utm\_source), login types, devices, and per-question answer distributions.         |
| `get_form_funnel` | Read a quiz's conversion funnel over the last N days: viewed → started → submitted → lead captured → report viewed → CTA clicked → shared, plus per-channel funnel and drop-off points. |
| `list_records`    | List the current team's submission records: respondent, answers, a compact report result and UTM; filter by quiz, report status and submitted time.                                     |
| `get_record`      | View one record's detail by its `id` (returned by `list_records`): full answers, report result and submission metadata.                                                                 |

### Image upload

| Tool                    | What it does                                                                                                                                        |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `prepare_image_upload`  | Step 1: issue a direct-upload URL for a cover/image (PUT the file to it).                                                                           |
| `finalize_image_upload` | Step 2: verify and record the image into the team media library, returning a media id; reference it via `update_form`'s `flagImg` / `landingImage`. |

<Callout type="info">
  Typical flows:

  * **From a template**: `list_templates` → `create_form_from_template` → adjust with `update_form` / `update_question`.
  * **Exam / scored quiz**: `create_form` to create the quiz and get each question's `code` → use `update_form` or `set_dimension_analysis` to configure report formulas / dimensions by `code`.
  * **Outcome quiz**: `create_form` in one call with `report.outcomes` (give each type a unique `code` of your own, e.g. `lion`) plus each choice's votes → after submission the type with the most votes wins (ties resolved by list order); fine-tune type copy / CTAs later via `update_form`.
  * **Launch**: `update_form_settings` to set the lead gate and result-page sections → `get_form_share_info` for the link and embed code.
</Callout>

## Current limitations

* **Question type can't be changed**: to switch type, `delete_question` then `add_question` to rebuild. Choices can be replaced as a whole with `update_question`, but **TrueFalse outcome votes** (`trueOutcomes` / `falseOutcomes`) still need delete + recreate.
* **Scene-specific scoring**: in the scored quiz and outcome quiz scenes `update_question` rejects the top-level `score` / `correctAnswer` / `aiMatch` — pass choices carrying `choices[i].score` (Option Scoring) or `choices[i].outcomes` (votes) instead.
* **Question types per scene**: Ordering is knowledge-quiz only; Rate is scored-quiz only; FillBlank in a scored quiz only collects data; outcome quizzes accept SingleCheck / MultiCheck / DropDown / TrueFalse (plus page breaks and display blocks).
* **Outcome images**: result-type **images** can't be uploaded via MCP yet — configure them in the editor (images already configured are kept when MCP updates `report.outcomes`).
* **Scene is locked** after creation; **language** can be changed only while the quiz has no language versions.
* **Delete is a soft delete**: `delete_form` moves to the trash (auto-purged after 5 days), not an immediate permanent delete; for permanent removal, delete again in the admin UI.
* **Question limit**: on the Free plan a quiz holds at most **50 questions** (page breaks, statements and image carousels don't count); `create_form`, `add_question` and `insert_question` are rejected past that. `duplicate_form` and `create_form_from_template` are not limited. Pro is unlimited — see [Question limit](https://docs.rooquiz.com/en/editor#question-limit).
* **Duplicate copies no data**: `duplicate_form` clones structure and translations only — it does **not** copy submission records or integrations (which hold secrets); the new quiz starts clean.
* **Respondent identity fields are immutable**: `update_examinee` can't change email, team, or `examineeId` (they are the auth identity).
* **Personal data comes back masked**: lead, booking, respondent and record tools return names, email addresses and phone numbers masked — including emails and phone numbers typed into answers. Masking is irreversible; refer to people by `examineeId`, `leadId` or record id.

## Security & rate limits

* OAuth or token, the AI acts **as you**, triggering existing access checks and **audit logs** (every write is recorded).
* Each connection is rate-limited to **60 requests / minute**; exceeding it returns a rate-limit error.
* When no longer needed, **revoke** (takes effect immediately; for OAuth connections this disconnects the client) or **delete** (also frees a slot) it in **Settings → MCP Integration**.
* The OAuth flow enforces **PKCE (S256)**, authorization codes are single-use, and refresh tokens rotate on every renewal — old ones become invalid immediately.
