MCP Integration

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.

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".

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.

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.

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

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.

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)

Templates

Form

Sharing & delivery settings

Question

Report dimensions

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).

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.

Leads

Bookings

Records & Analytics

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

Image upload

Current limitations

• Random Knowledge Quiz is not supported: its questions live in the QuestionBank — manage them in the editor; MCP doesn't cover them yet.
• 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; Cascade, Rate, DateField and TimeField are 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.
• Duplicate copies no data: duplicate_form clones structure and translations only — it does not copy submission records, sharing settings 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.