RooQuiz Docs
Intégrations et API

Intégration MCP

RooQuiz fournit un serveur MCP (Model Context Protocol) qui permet à des clients IA (ChatGPT, claude.ai, Claude Desktop, Claude Code, Cursor, Codex et d'autres) d'agir au sein de votre équipe. En langage naturel, vous pouvez créer des quiz à partir de modèles ou de zéro, ajouter et modifier des questions, configurer les dimensions du rapport ou les types de résultat, modifier les paramètres de diffusion et obtenir les liens de partage, gérer les traductions et les répondants, traiter vos leads, et consulter les réservations, les réponses, les statistiques et les entonnoirs de conversion, au lieu de tout faire à la main dans l'éditeur.

RooQuiz n'intègre pas de générateur de quiz par IA. Pour créer un quiz avec l'IA, connectez votre propre client IA via MCP et demandez-le-lui : il utilise les outils ci-dessous, et vous vérifiez le résultat dans l'éditeur.

MCP est une fonctionnalité destinée aux utilisateurs avancés : vous aurez besoin d'un client IA compatible MCP. Pour créer des quiz simplement et visuellement, nous recommandons toujours l'éditeur.

Fonctionnement

  • Un client IA se connecte au point de terminaison MCP de RooQuiz (/api/mcp) avec l'une des deux méthodes d'authentification : l'autorisation OAuth (recommandée : les clients compatibles se connectent simplement via le navigateur) ou un jeton API personnel.
  • Dans les deux cas, l'IA agit en votre nom au sein de l'équipe actuellement active.
  • Chaque action passe par les mêmes contrôles d'accès que l'interface d'administration ; les opérations d'écriture sont en outre enregistrées dans le journal d'audit.
  • Ce que l'IA peut faire est donc entièrement limité par votre rôle et vos autorisations dans cette équipe : elle ne peut pas les dépasser.

Option 1 : autorisation OAuth (recommandée)

Les clients compatibles avec OAuth pour MCP, comme ChatGPT, claude.ai et Claude Code, ne nécessitent aucun jeton créé manuellement. Il suffit de fournir l'URL du point de terminaison : le client découvre automatiquement le serveur d'autorisation et ouvre votre navigateur, où vous vous connectez à RooQuiz, choisissez l'équipe à autoriser et cliquez sur « Autoriser ».

RooQuiz est disponible sous forme d'application dans ChatGPT. Cliquez sur Use in ChatGPT en haut de l'interface d'administration de RooQuiz pour l'ouvrir, puis connectez-vous : votre navigateur est redirigé vers la page d'autorisation de RooQuiz ; connectez-vous, choisissez une équipe et cliquez sur « Autoriser ».

À propos des connexions OAuth :

  • L'équipe choisie lors de l'autorisation devient l'équipe active initiale ; l'IA peut toujours en changer ensuite via switch_active_tenant.
  • La connexion apparaît dans la liste des jetons sous Paramètres → Intégration MCP (avec l'étiquette OAuth) ; la révoquer déconnecte ce client. Elle n'est pas comptabilisée dans la limite de 5 jetons.
  • Les identifiants se renouvellent automatiquement (le jeton d'accès est actualisé toutes les heures de manière glissante ; la connexion elle-même reste valable 30 jours et se prolonge à l'usage) : rien à entretenir manuellement.

Option 2 : jeton personnel (PAT)

Pour les clients non compatibles avec OAuth (Cursor, Codex CLI, Claude Desktop) ou les environnements sans navigateur comme la CI, connectez-vous avec un jeton API personnel.

Créer un jeton

Rendez-vous dans Paramètres → Intégration MCP et cliquez sur Créer un jeton :

  1. Donnez-lui un Nom du jeton (pour le reconnaître, par exemple Cursor - my Mac).
  2. Choisissez une Équipe initiale : le jeton agit sur cette équipe par défaut, et l'IA peut ensuite passer à n'importe quelle autre équipe dont vous êtes membre via l'outil switch_active_tenant.
  3. Une fois le jeton créé, un jeton en clair commençant par rqp_live_ s'affiche.

Le jeton en clair n'est affiché qu'une seule fois. Il ne peut plus être récupéré une fois la page quittée. Copiez-le immédiatement ; en cas de perte, vous devrez le révoquer et en créer un nouveau.

Limites :

  • Chaque utilisateur peut détenir au maximum 5 jetons (jetons révoqués compris ; les connexions OAuth ne comptent pas). Pour en créer davantage, supprimez un jeton afin de libérer un emplacement (la « révocation » ne fait que désactiver le jeton, elle ne libère pas l'emplacement). Un jeton personnel révoqué peut être réactivé avec Activer.
  • Un jeton est un identifiant personnel : ne le commitez jamais dans votre gestionnaire de code source et ne le partagez jamais publiquement.

Configurer votre client IA

Sur la page Paramètres → Intégration MCP, vous pouvez copier des extraits de configuration prêts à l'emploi pour chaque client, ainsi que votre URL du point de terminaison (de la forme https://your-domain/api/mcp). Remplacez rqp_live_xxx... dans l'extrait par le jeton que vous venez de générer.

Pour Claude Code, privilégiez le flux OAuth décrit ci-dessus ; un en-tête de jeton n'est nécessaire que dans les environnements sans navigateur comme la CI :

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

Exemples de requêtes

Une fois votre client connecté, adressez-vous à lui en langage courant. Chacun de ces exemples sollicite une partie différente du serveur :

Partir d'un modèle

Montre-moi les modèles de coaching, crée un quiz noté à partir de celui sur la préparation, puis ajoute deux questions sur le budget.

Sollicite list_templates → create_form_from_template → add_question.

Traiter les leads

Liste les leads capturés cette semaine par mon quiz Roue de la vie, ajoute l'étiquette « à relancer » à tous ceux qui ont obtenu moins de 40 et attribue-les-moi.

Sollicite list_leads → set_lead_tags → assign_leads.

Diagnostiquer l'entonnoir

Lequel de mes quiz a le plus faible taux de complétion, et où exactement les gens abandonnent-ils ?

Sollicite list_forms → get_form_stats → get_form_funnel.

Passer au multilingue

Traduis mon quiz de préparation à la promotion en espagnol et en allemand, en conservant les codes des questions.

Sollicite list_form_translations → create_form_translation.

Les noms, adresses e-mail et numéros de téléphone des répondants sont renvoyés masqués (j***g@example.com). Le masquage est irréversible : désignez donc un répondant par son id plutôt que de recoller une valeur masquée dans une requête.

Outils disponibles

Une fois connecté, l'assistant IA peut appeler les 44 outils ci-dessous. Ils agissent tous sur l'équipe dans laquelle le jeton est actuellement actif.

Équipe (Tenant)

OutilRôle
list_my_tenantsListe toutes les équipes dont vous êtes membre, en indiquant celle qui est active.
get_active_tenantRenvoie l'équipe dans laquelle le jeton est actuellement actif (y compris son adresse d'équipe) ; toutes les écritures s'y appliquent par défaut.
switch_active_tenantChange l'équipe active (persiste d'une session à l'autre ; la cible doit être une équipe que vous avez rejointe).
invite_memberInvite une personne par e-mail dans l'équipe active en tant que membre ou administrateur ; un e-mail d'invitation contenant un lien pour rejoindre l'équipe est envoyé. Propriétaire / administrateur uniquement.
update_tenant_slugModifie l'adresse de l'équipe, c'est-à-dire le premier segment du chemin de chaque lien de quiz sur le domaine de la plateforme. Propriétaire / administrateur uniquement. Tous les liens publics des quiz changent en même temps et l'ancienne adresse cesse de fonctionner ; les liens /a/<token> continuent de fonctionner.

Modèles

OutilRôle
list_templatesListe les modèles actifs de la bibliothèque publique de modèles (titre, scène, description, catégorie, nombre d'utilisations), les plus utilisés en premier.
create_form_from_templateCrée un nouveau quiz à partir d'un modèle en un seul appel : structure, configuration de la notation / du rapport, paramètres visuels et toutes les versions linguistiques. C'est le moyen le plus rapide de créer un quiz lorsqu'un modèle adapté existe.

Formulaire

OutilRôle
create_formCrée un quiz (knowledge_quiz, scored_quiz ou quiz de profil outcome_quiz). Peut recevoir un tableau de questions et la configuration du rapport en un seul appel pour éviter les allers-retours. Un quiz de résultat doit inclure report.outcomes (la liste des types de résultat) dès sa création, chaque choix votant pour des types via outcomes.
list_formsListe les quiz de l'équipe actuelle, du plus récent au plus ancien, sans le contenu des questions.
get_formAffiche le détail complet d'un quiz (la liste de questions fields[], la configuration du rapport, etc.) ; appelez-le d'abord pour obtenir le code de chaque question avant toute modification. Pour les quiz de résultat, les code des types de résultat se trouvent dans report.outcomeAnalysis.outcomes.
update_formMet à jour le titre, la description, l'état ouvert/fermé, les couvertures (flagImg / landingImage), le thème, la carte de partage sur les réseaux sociaux (openGraph), les textes système, ou remplace par fusion la configuration report par sous-clé ; pour les quiz de résultat, passez report.outcomes pour mettre à jour par fusion les types de résultat selon leur code (les images configurées sont conservées, et la suppression d'un type encore référencé par des votes de questions est refusée). La langue ne peut être modifiée que tant que le quiz n'a aucune version linguistique ; la scène, jamais.
delete_formPlace un quiz dans la corbeille (suppression réversible) : il est masqué de list_forms et récupérable pendant 5 jours via restore_form (puis supprimé définitivement). Tout membre de l'équipe peut le supprimer ; les réponses sont conservées jusqu'à la suppression définitive.
restore_formRestaure depuis la corbeille un quiz supprimé par delete_form.
duplicate_formDuplique un quiz : copie sa structure de questions, sa notation, son rapport, ses éléments visuels et ses paramètres ainsi que toutes ses traductions dans un nouveau quiz qui vous appartient (avec de nouveaux liens). Ne copie pas les réponses, les intégrations ni l'état de blocage. newTitle facultatif.

Partage et paramètres de diffusion

OutilRôle
get_form_share_infoTout ce qu'il faut pour publier un quiz : le lien public de réponse (également par version linguistique), le domaine personnalisé de l'équipe et s'il est actif, les extraits d'intégration en trois modes (inline / popup / iframe) et les paramètres de diffusion actuels. Passez utmSource pour baliser chaque lien et chaque extrait pour un canal donné.
update_form_settingsModifie la façon dont un quiz est diffusé : qui peut répondre et si le rapport exige un e-mail (la barrière de capture de leads) et un code de vérification, la limite de temps (quiz de connaissances), le partage et la carte de partage, la feuille de réponses, la comparaison avec les autres, la section de réservation de la page de résultats et son lien Cal.com, le bloc de retours, le téléchargement PDF (Pro), l'ID Google Analytics, etc.

Question

OutilRôle
add_questionAjoute un élément à la fin : une question, un saut de page (Breaker) ou un bloc d'affichage (passage de texte enrichi Statement, carrousel d'images Swiper). Types de questions : SingleCheck / MultiCheck / TrueFalse, FillBlank, DropDown, Ordering (quiz de connaissances), NumberField et Rate (quiz noté). Dans un quiz de résultat, chaque choix doit déclarer les types de résultat pour lesquels il vote (TrueFalse utilise trueOutcomes / falseOutcomes).
insert_questionInsère un élément à une position précise, en utilisant after / before pour référencer un code existant.
move_questionDéplace une question ou un saut de page existant vers une nouvelle position, selon son code.
update_questionMet à jour une question selon son code : énoncé, note, explication, caractère obligatoire, score, bonne réponse, correction IA d'une question FillBlank, options de nombre / date / notation, ou remplacement de tous les choix d'une question à choix. Les blocs d'affichage se modifient également ici. Ne peut pas modifier le type de question.
delete_questionSupprime une question ou un saut de page selon son code.

Dimensions du rapport

OutilRôle
set_dimension_analysisDéfinit en bloc l'analyse multidimensionnelle d'un quiz (dimensions du graphique radar) ; seul scored_quiz a des dimensions, chacune utilisant une formule sur des code de questions (les quiz de connaissances n'ont pas de dimensions). Passez un tableau vide pour l'effacer. Ne s'applique pas aux quiz de résultat (ils n'ont pas de dimensions : configurez plutôt les types de résultat via report.outcomes).

Traductions (FormTranslation)

Proposez un quiz en plusieurs langues : un quiz source (langue principale) plus une traduction par langue supplémentaire (même structure que la source, seul le texte est traduit ; les réponses sont toujours rattachées au quiz source).

OutilRôle
create_form_translationAjoute une version linguistique à un quiz en clonant le contenu source comme brouillon initial (mêmes code, texte dans la langue source), et renvoie ce contenu pour le traduire immédiatement. La langue doit être différente de la langue principale, avec au maximum une version par langue.
list_form_translationsListe les versions linguistiques existantes d'un quiz (langue, état actif, lien public, etc.).
get_form_translationLit le contenu complet d'une version linguistique (y compris fields[] et report) pour le traduire sur place ; chaque code doit rester identique à la source.
update_form_translationEnregistre le texte traduit d'une version linguistique (title / description / fields / report / systemText), ou la met en pause via isActive ; la structure est fixée par la source, vous ne modifiez que le texte, et les champs omis sont considérés comme une traduction partielle.
delete_form_translationSupprime une version linguistique.

Répondants (examinees)

Les personnes qui répondent à un quiz, appelées Répondants dans l'interface d'administration ; les outils conservent le terme examinee. Chaque répondant est rattaché à une seule équipe ; les outils ne renvoient que des champs sûrs : le mot de passe, le code de vérification, le jeton de réinitialisation et les autres champs sensibles ne sont jamais exposés.

OutilRôle
list_examineesListe les répondants de l'équipe actuelle, avec une recherche approximative facultative par e-mail / nom et un filtre par statut (actif / désactivé).
get_examineeAffiche le détail d'un répondant (y compris les données personnalisées customData) à partir de son identifiant métier examineeId (par exemple AB1234567890, affiché dans la liste).
update_examineeModifie le nom, le statut ou les customData d'un répondant à partir de son examineeId (les customData sont validées selon les définitions de champs de l'équipe et remplacent l'objet entier). L'e-mail et l'équipe ne peuvent pas être modifiés.

Leads

OutilRôle
list_leadsListe les leads de l'équipe (un par répondant, tous quiz confondus), avec le statut de suivi, le responsable, les étiquettes de couleur, le nombre de réponses et la prochaine réservation. Filtre par statut / responsable / étiquettes / date de création / mot-clé / réservation à venir.
get_leadAffiche un lead à partir de son leadId, avec en option l'historique des réponses du répondant, les commentaires internes de l'équipe et la chronologie des modifications.
list_lead_settingsLit les statuts de suivi, la bibliothèque d'étiquettes et les membres assignables de l'équipe. Appelez-le avant toute écriture : les codes de statut, les codes d'étiquette et les id de membres sont propres à chaque équipe.
update_leadFait passer un lead à un autre statut de suivi (par exemple new → contacted) ; le changement est enregistré dans la chronologie du lead.
assign_leadsAttribue jusqu'à 50 leads en un seul appel à un membre actif ("me" pour vous-même), ou retire le responsable. La personne assignée reçoit une seule notification groupée.
set_lead_tagsDéfinit les étiquettes de couleur de jusqu'à 50 leads en un seul appel : replace (un seul lead), ou add / remove pour les lots afin de préserver les étiquettes posées par d'autres.
add_lead_commentRédige un commentaire de suivi interne sur un lead (réservé à l'équipe, jamais montré au répondant), éventuellement rattaché à une réponse.

Réservations

OutilRôle
list_bookingsListe les réservations de l'équipe synchronisées depuis Cal.com, des plus proches aux plus lointaines, avec l'horaire, le statut, le type d'événement Cal.com, le participant, le quiz et la réponse d'origine, et le responsable du lead. Filtre par statut / quiz / répondant / période. Lecture seule : les réservations se modifient dans Cal.com.

Réponses et analyses

Consultez les performances des quiz et les réponses pour que l'IA puisse boucler le cycle création → mesure → itération.

OutilRôle
get_form_statsLit les statistiques d'un quiz sur les N derniers jours (30 par défaut, 180 au maximum) : vue d'ensemble des KPI, tendance quotidienne, canaux (utm_source), types de connexion, appareils et répartition des réponses par question.
get_form_funnelLit l'entonnoir de conversion d'un quiz sur les N derniers jours : vu → commencé → soumis → lead capturé → rapport consulté → CTA cliqué → partagé, ainsi que l'entonnoir par canal et les points d'abandon.
list_recordsListe les réponses de l'équipe actuelle : répondant, réponses, résultat compact du rapport et UTM ; filtre par quiz, statut du rapport et date de soumission.
get_recordAffiche le détail d'une réponse à partir de son id (renvoyé par list_records) : réponses complètes, résultat du rapport et métadonnées de soumission.

Téléversement d'images

OutilRôle
prepare_image_uploadÉtape 1 : génère une URL de téléversement direct pour une couverture ou une image (envoyez-y le fichier en PUT).
finalize_image_uploadÉtape 2 : vérifie et enregistre l'image dans la médiathèque de l'équipe, et renvoie un id de média ; référencez-le via flagImg / landingImage dans update_form.

Parcours types :

  • À partir d'un modèle : list_templates → create_form_from_template → ajustez avec update_form / update_question.
  • Examen / quiz noté : create_form pour créer le quiz et obtenir le code de chaque question → utilisez update_form ou set_dimension_analysis pour configurer les formules / dimensions du rapport selon les code.
  • Quiz de résultat : create_form en un seul appel avec report.outcomes (attribuez à chaque type un code unique de votre choix, par exemple lion) ainsi que les votes de chaque choix → après la soumission, le type ayant obtenu le plus de votes l'emporte (en cas d'égalité, l'ordre de la liste prévaut) ; ajustez ensuite les textes et CTA des types via update_form.
  • Lancement : update_form_settings pour définir la barrière de capture de leads et les sections de la page de résultats → get_form_share_info pour le lien et le code d'intégration.

Limites actuelles

  • Le type de question ne peut pas être modifié : pour changer de type, utilisez delete_question puis add_question pour reconstruire la question. Les choix peuvent être remplacés en bloc avec update_question, mais les votes de résultat d'une question TrueFalse (trueOutcomes / falseOutcomes) nécessitent toujours une suppression puis une recréation.
  • Notation propre à chaque scène : dans les scènes du quiz noté et du quiz de résultat, update_question refuse les paramètres de premier niveau score / correctAnswer / aiMatch ; passez plutôt des choix portant choices[i].score (notation par option) ou choices[i].outcomes (votes).
  • Types de questions par scène : Ordering est réservé au quiz de connaissances ; Rate est réservé au quiz noté ; dans un quiz noté, FillBlank ne fait que recueillir des données ; les quiz de résultat acceptent SingleCheck / MultiCheck / DropDown / TrueFalse (ainsi que les sauts de page et les blocs d'affichage).
  • Images des résultats : les images des types de résultat ne peuvent pas encore être téléversées via MCP : configurez-les dans l'éditeur (les images déjà configurées sont conservées lorsque MCP met à jour report.outcomes).
  • La scène est verrouillée après la création ; la langue ne peut être modifiée que tant que le quiz n'a aucune version linguistique.
  • La suppression est réversible : delete_form place le quiz dans la corbeille (purgée automatiquement après 5 jours), il ne s'agit pas d'une suppression définitive immédiate ; pour une suppression définitive, supprimez-le à nouveau dans l'interface d'administration.
  • Limite de questions : avec le forfait Free, un quiz contient au maximum 50 questions (les sauts de page, les blocs de texte enrichi et les carrousels d'images ne comptent pas) ; au-delà, create_form, add_question et insert_question sont refusés. duplicate_form et create_form_from_template ne sont pas limités. Le forfait Pro est illimité : consultez Limite de questions.
  • La duplication ne copie aucune donnée : duplicate_form ne clone que la structure et les traductions ; elle ne copie pas les réponses ni les intégrations (qui contiennent des secrets). Le nouveau quiz démarre vierge.
  • Les champs d'identité des répondants sont immuables : update_examinee ne peut pas modifier l'e-mail, l'équipe ni l'examineeId (ils constituent l'identité d'authentification).
  • Les données personnelles sont renvoyées masquées : les outils de leads, de réservations, de répondants et de réponses renvoient les noms, adresses e-mail et numéros de téléphone masqués, y compris les e-mails et numéros saisis dans les réponses. Le masquage est irréversible ; désignez les personnes par examineeId, leadId ou l'id de la réponse.

Sécurité et limites de débit

  • Via OAuth comme via jeton, l'IA agit en votre nom, ce qui déclenche les contrôles d'accès existants et les journaux d'audit (chaque écriture est enregistrée).
  • Chaque connexion est limitée à 60 requêtes par minute ; au-delà, une erreur de limite de débit est renvoyée.
  • Lorsque vous n'en avez plus besoin, révoquez-la (effet immédiat ; pour les connexions OAuth, cela déconnecte le client) ou supprimez-la (ce qui libère aussi un emplacement) dans Paramètres → Intégration MCP.
  • Le flux OAuth impose PKCE (S256), les codes d'autorisation sont à usage unique et les jetons d'actualisation changent à chaque renouvellement : les anciens deviennent immédiatement invalides.

Sur cette page