MCP Integration

RooQuiz ships an MCP (Model Context Protocol) server that lets AI clients — Claude Desktop, Claude Code, Cursor, Codex, and others — operate on quizzes inside your team. With natural language you can create quizzes, scorecards, and outcome quizzes, append questions, reorder items, and configure report dimensions or outcome types; you can also duplicate / delete quizzes, manage translations and examinees, and read submission records, stats and conversion funnels — instead of building 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 — 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”.

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

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 name (for recognition, e.g. Cursor - my Mac).
2. Pick a default 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 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..."

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

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

export ROOQUIZ_MCP_TOKEN="rqp_live_xxx..."

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

Available tools

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

Team (Tenant)

Form

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

Examinees

The people who take a quiz. 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.

Records & Analytics

Read quiz performance, conversion funnels and leads so the AI can close the build → measure → iterate loop. The lead tools return respondent info (PII).

Image upload

Current limitations

• Random Quiz is not supported: its questions live in the QuestionBank — manage them in the editor; MCP doesn’t cover them yet.
• Can’t change question type or choices directly: to switch type or edit choices, delete_question then add_question to rebuild. The same applies to an outcome quiz’s choice-to-type vote mapping — to change votes, rebuild the question.
• Scorecard choice scoring uses Option Scoring: in the scorecard scene update_question rejects score / correctAnswer / aiMatch. Edit choice scores in the admin UI, or delete and recreate. The outcome scene rejects those three parameters likewise (it decides by votes — there is no scoring).
• Outcome quiz question types: voting questions are SingleCheck / MultiCheck / TrueFalse (FillBlank is not supported); 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 and language are locked after creation and can’t be changed via MCP.
• 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.
• 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.
• Examinee identity fields are immutable: update_examinee can’t change email, team, or examineeId (they are the auth identity).
• Leads contain PII: list_records / get_record return respondent email, name, custom fields, etc. — handle them responsibly.
• FillBlank AI grading (aiMatch, quiz scene only, Beta) consumes your team’s AI credits.

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.