RooQuiz Doku
Integrationen & API

MCP-Integration

RooQuiz bietet einen MCP-Server (Model Context Protocol), über den KI-Clients – ChatGPT, claude.ai, Claude Desktop, Claude Code, Cursor, Codex und andere – in Ihrem Team arbeiten können. Per natürlicher Sprache können Sie Quizze aus Vorlagen oder von Grund auf erstellen, Fragen anhängen und bearbeiten, Berichtsdimensionen oder Ergebnistypen konfigurieren, Auslieferungseinstellungen ändern und Freigabelinks abrufen, Übersetzungen und Teilnehmer verwalten, Ihre Leads bearbeiten sowie Buchungen, Einsendungen, Statistiken und Conversion-Funnels lesen – statt alles von Hand im Editor zu erledigen.

RooQuiz hat keinen integrierten KI-Quizgenerator. Um ein Quiz mit KI zu erstellen, verbinden Sie Ihren eigenen KI-Client über MCP und bitten ihn darum – er nutzt die unten aufgeführten Tools, und Sie prüfen das Ergebnis im Editor.

MCP ist eine Funktion für erfahrene Nutzer – Sie benötigen einen KI-Client, der MCP unterstützt. Für das einfache, visuelle Erstellen von Quizzen empfehlen wir weiterhin den Editor.

Funktionsweise

  • Ein KI-Client verbindet sich mit dem MCP-Endpunkt von RooQuiz (/api/mcp) über eine von zwei Authentifizierungsmethoden: OAuth-Autorisierung (empfohlen – unterstützte Clients melden sich einfach über den Browser an) oder ein persönliches API-Token.
  • In beiden Fällen handelt die KI als Sie innerhalb des gerade aktiven Teams.
  • Jede Aktion durchläuft dieselben Zugriffsprüfungen wie die Admin-Oberfläche; Schreibvorgänge werden außerdem im Audit-Log erfasst.
  • Was die KI tun kann, ist also vollständig durch Ihre Rolle und Berechtigungen in diesem Team begrenzt – sie kann diese nicht überschreiten.

Option 1: OAuth-Autorisierung (empfohlen)

Clients, die MCP-OAuth unterstützen – ChatGPT, claude.ai und Claude Code –, benötigen kein manuell erstelltes Token. Geben Sie einfach die Endpunkt-URL an: Der Client erkennt den Autorisierungsserver automatisch und öffnet Ihren Browser, wo Sie sich bei RooQuiz anmelden, das zu autorisierende Team auswählen und auf „Autorisieren“ klicken.

RooQuiz ist als App in ChatGPT verfügbar. Klicken Sie oben in der RooQuiz-Administration auf In ChatGPT verwenden, um sie zu öffnen, und verbinden Sie sich dann – Ihr Browser wird zur Autorisierungsseite von RooQuiz weitergeleitet; melden Sie sich an, wählen Sie ein Team und klicken Sie auf „Autorisieren“.

Zu OAuth-Verbindungen:

  • Das Team, das Sie bei der Autorisierung auswählen, wird zum anfänglich aktiven Team; die KI kann später über switch_active_tenant trotzdem wechseln.
  • Die Verbindung erscheint in der Token-Liste unter Einstellungen → MCP-Integration (markiert mit OAuth); Widerrufen trennt diesen Client. Sie zählt nicht zum Limit von 5 Tokens.
  • Die Anmeldedaten werden automatisch erneuert (das Access-Token wird fortlaufend stündlich aktualisiert; die Verbindung selbst bleibt 30 Tage gültig und verlängert sich bei Nutzung) – Sie müssen nichts von Hand pflegen.

Option 2: Persönliches Token (PAT)

Für Clients ohne OAuth-Unterstützung (Cursor, Codex CLI, Claude Desktop) oder Umgebungen ohne Browser wie CI verbinden Sie sich mit einem persönlichen API-Token.

Token erstellen

Öffnen Sie Einstellungen → MCP-Integration und klicken Sie auf Token erstellen:

  1. Vergeben Sie einen Token-Namen (zur Wiedererkennung, z. B. Cursor - my Mac).
  2. Wählen Sie ein Anfängliches Team – das Token arbeitet standardmäßig mit diesem Team, und die KI kann später über das Tool switch_active_tenant zu jedem anderen Team wechseln, dem Sie angehören.
  3. Nach dem Erstellen wird ein Klartext-Token angezeigt, das mit rqp_live_ beginnt.

Das Klartext-Token wird nur ein einziges Mal angezeigt. Nachdem Sie die Seite verlassen haben, kann es nicht mehr abgerufen werden. Kopieren Sie es sofort; geht es verloren, müssen Sie es widerrufen und ein neues erstellen.

Limits:

  • Jeder Nutzer kann höchstens 5 Tokens besitzen (einschließlich widerrufener; OAuth-Verbindungen zählen nicht). Um weitere zu erstellen, löschen Sie eines, um einen Platz freizugeben („Widerrufen“ deaktiviert nur – der Platz wird dadurch nicht frei). Ein widerrufenes persönliches Token lässt sich mit Aktivieren wieder einschalten.
  • Ein Token ist eine persönliche Zugangsberechtigung – committen Sie es niemals in die Versionsverwaltung und teilen Sie es nicht öffentlich.

KI-Client konfigurieren

Auf der Seite Einstellungen → MCP-Integration können Sie fertige Konfigurations-Snippets für jeden Client kopieren, zusammen mit Ihrer Endpunkt-URL (sieht aus wie https://your-domain/api/mcp). Ersetzen Sie rqp_live_xxx... im Snippet durch das soeben erzeugte Token.

Für Claude Code ist der oben beschriebene OAuth-Ablauf vorzuziehen; ein Token-Header wird nur in Umgebungen ohne Browser wie CI benötigt:

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

Beispiel-Prompts

Sobald Ihr Client verbunden ist, sprechen Sie in normaler Sprache mit ihm. Jedes dieser Beispiele nutzt einen anderen Teil des Servers:

Aus einer Vorlage erstellen

Zeig mir die Coaching-Vorlagen, erstelle aus der Readiness-Vorlage ein bewertetes Quiz und füge dann zwei Fragen zum Budget hinzu.

Nutzt list_templates → create_form_from_template → add_question.

Leads bearbeiten

Liste die Leads auf, die mein Wheel-of-Life-Quiz diese Woche erfasst hat, tagge alle mit einer Punktzahl unter 40 als Follow-up und weise sie mir zu.

Nutzt list_leads → set_lead_tags → assign_leads.

Den Funnel analysieren

Welches meiner Quizze hat die schlechteste Abschlussrate, und wo genau springen die Leute ab?

Nutzt list_forms → get_form_stats → get_form_funnel.

Mehrsprachig werden

Übersetze mein Quiz zur Beförderungsreife ins Spanische und Deutsche und behalte die Fragecodes bei.

Nutzt list_form_translations → create_form_translation.

Namen, E-Mail-Adressen und Telefonnummern von Teilnehmern werden maskiert zurückgegeben (j***g@example.com). Die Maskierung ist nicht umkehrbar – verweisen Sie daher über die ID auf einen Teilnehmer, statt einen maskierten Wert in einen Prompt zurückzukopieren.

Verfügbare Tools

Nach dem Verbinden kann der KI-Assistent die folgenden 44 Tools aufrufen. Sie wirken alle auf das Team, in dem das Token gerade aktiv ist.

Team (Tenant)

ToolFunktion
list_my_tenantsListet alle Teams auf, denen Sie angehören, und markiert das gerade aktive.
get_active_tenantGibt das Team zurück, in dem das Token gerade aktiv ist (einschließlich seiner Team-Adresse); alle Schreibvorgänge beziehen sich standardmäßig darauf.
switch_active_tenantWechselt das aktive Team (bleibt sitzungsübergreifend erhalten; das Ziel muss ein Team sein, dem Sie beigetreten sind).
invite_memberLädt eine Person per E-Mail als Mitglied oder Administrator in das aktive Team ein; es wird eine Einladungs-E-Mail mit Beitrittslink versendet. Nur für Inhaber / Administratoren.
update_tenant_slugÄndert die Team-Adresse – das erste Pfadsegment jedes Quiz-Links auf der Plattform-Domain. Nur für Inhaber / Administratoren. Alle öffentlichen Quiz-Links ändern sich auf einmal, und die alte Adresse funktioniert nicht mehr; /a/<token>-Links funktionieren weiterhin.

Vorlagen

ToolFunktion
list_templatesListet die aktiven Vorlagen der öffentlichen Vorlagenbibliothek auf (Titel, Szene, Beschreibung, Kategorie, Nutzungszahl), die meistgenutzten zuerst.
create_form_from_templateErstellt in einem Aufruf ein neues Quiz aus einer Vorlage: Struktur, Bewertungs- / Berichtskonfiguration, Gestaltung und alle Sprachversionen. Der schnellste Weg zu einem Quiz, wenn es eine passende Vorlage gibt.

Formular

ToolFunktion
create_formErstellt ein Quiz (knowledge_quiz, scored_quiz oder outcome_quiz als Typen-Quiz). Kann in einem Aufruf ein Fragen-Array und die Berichtskonfiguration entgegennehmen, um Hin- und Her-Aufrufe zu vermeiden. Ein Ergebnisquiz muss beim Erstellen report.outcomes (die Liste der Ergebnistypen) enthalten, wobei jede Auswahloption über outcomes für Typen stimmt.
list_formsListet die Quizze des aktuellen Teams auf, die neuesten zuerst, ohne Frageninhalte.
get_formZeigt alle Details eines Quiz an (die Fragenliste fields[], die Berichtskonfiguration usw.); rufen Sie dies vor dem Bearbeiten zuerst auf, um den code jeder Frage zu erhalten – bei Ergebnisquizzen liegen die codes der Ergebnistypen in report.outcomeAnalysis.outcomes.
update_formAktualisiert Titel, Beschreibung, Status geöffnet/geschlossen, Titelbilder (flagImg / landingImage), Theme, Social-Share-Card (openGraph), Systemtexte oder ersetzt die report-Konfiguration zusammenführend pro Unterschlüssel; bei Ergebnisquizzen übergeben Sie report.outcomes, um Ergebnistypen per code zusammenführend zu aktualisieren (konfigurierte Bilder bleiben erhalten, und das Entfernen eines Typs, auf den noch Stimmen von Fragen verweisen, wird abgelehnt). Die Sprache lässt sich nur ändern, solange das Quiz keine Sprachversionen hat; die Szene nie.
delete_formVerschiebt ein Quiz in den Papierkorb (Soft Delete): ausgeblendet in list_forms, 5 Tage lang über restore_form wiederherstellbar (danach endgültig gelöscht). Jedes Teammitglied kann löschen; Einsendungen bleiben bis zur endgültigen Löschung erhalten.
restore_formStellt ein mit delete_form gelöschtes Quiz aus dem Papierkorb wieder her.
duplicate_formDupliziert ein Quiz: klont Fragenstruktur, Bewertung, Bericht, Gestaltung und Einstellungen sowie alle Sprachübersetzungen in ein neues Quiz in Ihrem Besitz (mit neuen Links). Kopiert keine Einsendungen, Integrationen oder Sperrstatus. Optional newTitle.

Teilen & Auslieferungseinstellungen

ToolFunktion
get_form_share_infoAlles, was zum Veröffentlichen eines Quiz nötig ist: der öffentliche Antwortlink (auch pro Sprachversion), die benutzerdefinierte Domain des Teams und ob sie aktiv ist, Einbettungs-Snippets in drei Modi (inline / popup / iframe) und die aktuellen Auslieferungseinstellungen. Übergeben Sie utmSource, um jeden Link und jedes Snippet für einen Kanal zu kennzeichnen.
update_form_settingsÄndert, wie ein Quiz ausgeliefert wird: wer antworten darf und ob der Bericht eine E-Mail-Adresse (die Lead-Abfrage) und einen Bestätigungscode erfordert, Zeitlimit (Wissensquizze), Teilen und Share-Karte, Antwortbogen, Gruppenvergleich, der Buchungsbereich der Ergebnisseite samt Cal.com-Link, der Feedback-Block, PDF-Download (Pro), Google-Analytics-ID und mehr.

Frage

ToolFunktion
add_questionHängt ein Element am Ende an: eine Frage, einen Seitenumbruch (Breaker) oder einen Anzeigeblock (Statement als Rich-Text-Abschnitt, Swiper als Bildkarussell). Fragetypen: SingleCheck / MultiCheck / TrueFalse, FillBlank, DropDown, Ordering (Wissensquiz), NumberField und Rate (Bewertetes Quiz). In einem Ergebnisquiz muss jede Auswahloption angeben, für welche Ergebnistypen sie stimmt (TrueFalse verwendet trueOutcomes / falseOutcomes).
insert_questionFügt ein Element an einer bestimmten Position ein und verweist mit after / before auf einen vorhandenen code.
move_questionVerschiebt eine vorhandene Frage oder einen Seitenumbruch per code an eine neue Position.
update_questionAktualisiert eine Frage per code: Fragetext, Hinweis, Erklärung, Pflichtfeld-Status, Punktzahl, richtige Antwort, KI-Bewertung bei FillBlank, Zahlen- / Datums- / Bewertungsoptionen oder ersetzt alle Auswahloptionen einer Auswahlfrage. Auch Anzeigeblöcke werden hier bearbeitet. Der Fragetyp kann nicht geändert werden.
delete_questionLöscht eine Frage oder einen Seitenumbruch per code.

Berichtsdimensionen

ToolFunktion
set_dimension_analysisLegt die Mehrdimensionsanalyse eines Quiz (Dimensionen des Netzdiagramms) als Ganzes fest; nur scored_quiz hat Dimensionen, jede nutzt eine Formel über Fragen-codes (Wissensquizze haben keine Dimensionen). Übergeben Sie ein leeres Array zum Leeren. Nicht für Ergebnisquizze anwendbar (sie haben keine Dimensionen – konfigurieren Sie Ergebnistypen stattdessen über report.outcomes).

Übersetzungen (FormTranslation)

Bieten Sie ein Quiz in mehreren Sprachen an: ein Quell-Quiz (Hauptsprache) plus eine Übersetzung pro weiterer Sprache (gleiche Struktur wie die Quelle, nur der Text wird übersetzt; Einsendungen sind immer dem Quell-Quiz zugeordnet).

ToolFunktion
create_form_translationFügt einem Quiz eine Sprachversion hinzu, klont die Quelltexte als ersten Entwurf (gleiche codes, Text in der Quellsprache) und gibt diesen Inhalt zur sofortigen Übersetzung zurück. Die Sprache muss sich von der Hauptsprache unterscheiden, höchstens eine pro Sprache.
list_form_translationsListet die vorhandenen Sprachversionen eines Quiz auf (Sprache, Aktiv-Status, öffentlicher Link usw.).
get_form_translationLiest den vollständigen Inhalt einer Sprachversion (einschließlich fields[] und report), um ihn direkt zu übersetzen – jeder code muss mit der Quelle identisch bleiben.
update_form_translationSpeichert die übersetzten Texte einer Sprachversion (title / description / fields / report / systemText) oder pausiert sie über isActive; die Struktur ist durch die Quelle festgelegt, Sie ändern nur Text, und ausgelassene Felder gelten als teilweise Übersetzung.
delete_form_translationLöscht eine Sprachversion.

Teilnehmer (Examinees)

Die Personen, die ein Quiz absolvieren – in der Admin-Oberfläche „Teilnehmer“ genannt; die Tools behalten die Bezeichnung „examinee“ bei. Jeder Teilnehmer ist an genau ein Team gebunden; die Tools geben nur unbedenkliche Felder zurück – Passwort, Bestätigungscode, Reset-Token und andere sensible Felder werden niemals offengelegt.

ToolFunktion
list_examineesListet die Teilnehmer des aktuellen Teams auf, optional mit unscharfer Suche nach E-Mail / Name und Filterung nach Status (aktiv / deaktiviert).
get_examineeZeigt die Details eines Teilnehmers (einschließlich benutzerdefinierter customData) anhand seiner Geschäfts-ID examineeId an (z. B. AB1234567890, in der Liste angezeigt).
update_examineeBearbeitet Name / Status / customData eines Teilnehmers per examineeId (customData wird gegen die Felddefinitionen des Teams validiert und ersetzt das gesamte Objekt). E-Mail und Team können nicht geändert werden.

Leads

ToolFunktion
list_leadsListet die Leads des Teams auf – einer pro Teilnehmer über alle Quizze hinweg, mit Nachfass-Status, Zuständigem, Farbmarkierungen, Anzahl der Einsendungen und nächster Buchung. Filterbar nach Status / Zuständigem / Markierungen / Erstellungsdatum / Stichwort / anstehender Buchung.
get_leadZeigt einen Lead per leadId an, optional mit der Einsendungshistorie des Teilnehmers, den internen Kommentaren des Teams und dem Änderungsverlauf.
list_lead_settingsLiest die Nachfass-Status, die Markierungsbibliothek und die zuweisbaren Mitglieder des Teams. Rufen Sie dies vor dem Schreiben auf – Status-Codes, Markierungs-Codes und Mitglieds-IDs sind teamspezifisch.
update_leadVerschiebt einen Lead in einen anderen Nachfass-Status (z. B. neu → kontaktiert); wird im Verlauf des Leads festgehalten.
assign_leadsWeist in einem Aufruf bis zu 50 Leads einem aktiven Mitglied zu ("me" für Sie selbst), oder entfernt die Zuweisung. Der Zuständige erhält eine gesammelte Benachrichtigung.
set_lead_tagsSetzt Farbmarkierungen für bis zu 50 Leads in einem Aufruf: replace (einzelner Lead) oder add / remove für Stapel, damit die Markierungen anderer erhalten bleiben.
add_lead_commentSchreibt einen internen Nachfass-Kommentar zu einem Lead (nur für das Team, nie für den Teilnehmer sichtbar), optional mit Bezug auf eine Einsendung.

Buchungen

ToolFunktion
list_bookingsListet die aus Cal.com synchronisierten Buchungen des Teams auf, die frühesten zuerst, mit Zeit, Status, Cal.com-Event-Typ, teilnehmender Person, Quell-Quiz und Einsendung sowie Lead-Verantwortlichem. Filterbar nach Status / Quiz / Teilnehmer / Zeitraum. Schreibgeschützt – Buchungen werden in Cal.com geändert.

Einsendungen & Analysen

Lesen Sie Quiz-Performance und Einsendungen, damit die KI den Kreislauf aus Erstellen → Messen → Verbessern schließen kann.

ToolFunktion
get_form_statsLiest die Statistiken eines Quiz über die letzten N Tage (Standard 30, max. 180): KPI-Übersicht, täglicher Verlauf, Kanäle (utm_source), Anmeldearten, Geräte und Antwortverteilungen pro Frage.
get_form_funnelLiest den Conversion-Funnel eines Quiz über die letzten N Tage: angesehen → begonnen → abgesendet → Lead erfasst → Bericht angesehen → CTA geklickt → geteilt, dazu Funnel pro Kanal und Abbruchpunkte.
list_recordsListet die Einsendungen des aktuellen Teams auf: Teilnehmer, Antworten, ein kompaktes Berichtsergebnis und UTM; filterbar nach Quiz, Berichtsstatus und Einsendezeit.
get_recordZeigt die Details einer Einsendung anhand ihrer id (von list_records zurückgegeben) an: vollständige Antworten, Berichtsergebnis und Einsendungs-Metadaten.

Bild-Upload

ToolFunktion
prepare_image_uploadSchritt 1: stellt eine Direkt-Upload-URL für ein Titelbild/Bild aus (die Datei per PUT dorthin senden).
finalize_image_uploadSchritt 2: prüft das Bild, übernimmt es in die Medienbibliothek des Teams und gibt eine Medien-ID zurück; referenzieren Sie es über flagImg / landingImage von update_form.

Typische Abläufe:

  • Aus einer Vorlage: list_templates → create_form_from_template → mit update_form / update_question anpassen.
  • Prüfung / bewertetes Quiz: Mit create_form das Quiz erstellen und den code jeder Frage erhalten → mit update_form oder set_dimension_analysis Berichtsformeln / Dimensionen per code konfigurieren.
  • Ergebnisquiz: create_form in einem Aufruf mit report.outcomes (geben Sie jedem Typ einen eigenen eindeutigen code, z. B. lion) plus den Stimmen jeder Auswahloption → nach dem Absenden gewinnt der Typ mit den meisten Stimmen (bei Gleichstand entscheidet die Reihenfolge in der Liste); Texte / CTAs der Typen später über update_form feinjustieren.
  • Veröffentlichen: Mit update_form_settings die Lead-Abfrage und die Bereiche der Ergebnisseite festlegen → mit get_form_share_info Link und Einbettungscode abrufen.

Aktuelle Einschränkungen

  • Der Fragetyp lässt sich nicht ändern: Um den Typ zu wechseln, verwenden Sie delete_question und dann add_question, um die Frage neu aufzubauen. Auswahloptionen lassen sich mit update_question als Ganzes ersetzen, aber TrueFalse-Stimmen im Ergebnisquiz (trueOutcomes / falseOutcomes) erfordern weiterhin Löschen und Neuanlegen.
  • Szenenspezifische Bewertung: In den Szenen Bewertetes Quiz und Ergebnisquiz lehnt update_question die Parameter score / correctAnswer / aiMatch auf oberster Ebene ab – übergeben Sie stattdessen Auswahloptionen mit choices[i].score (Option Scoring) oder choices[i].outcomes (Stimmen).
  • Fragetypen pro Szene: Ordering gibt es nur im Wissensquiz; Rate nur im Bewerteten Quiz; FillBlank erfasst im Bewerteten Quiz nur Daten; Ergebnisquizze akzeptieren SingleCheck / MultiCheck / DropDown / TrueFalse (plus Seitenumbrüche und Anzeigeblöcke).
  • Ergebnisbilder: Bilder von Ergebnistypen können noch nicht über MCP hochgeladen werden – konfigurieren Sie sie im Editor (bereits konfigurierte Bilder bleiben erhalten, wenn MCP report.outcomes aktualisiert).
  • Die Szene ist nach dem Erstellen gesperrt; die Sprache lässt sich nur ändern, solange das Quiz keine Sprachversionen hat.
  • Löschen ist ein Soft Delete: delete_form verschiebt in den Papierkorb (nach 5 Tagen automatisch endgültig gelöscht), es löscht nicht sofort endgültig; für die endgültige Entfernung löschen Sie erneut in der Admin-Oberfläche.
  • Fragenlimit: Im Free-Tarif enthält ein Quiz höchstens 50 Fragen (Seitenumbrüche, Rich-Text-Blöcke und Bildkarussells zählen nicht); create_form, add_question und insert_question werden darüber hinaus abgelehnt. duplicate_form und create_form_from_template sind nicht begrenzt. Pro ist unbegrenzt – siehe Fragenlimit.
  • Duplizieren kopiert keine Daten: duplicate_form klont nur Struktur und Übersetzungen – es kopiert keine Einsendungen oder Integrationen (die Geheimnisse enthalten); das neue Quiz startet leer.
  • Identitätsfelder von Teilnehmern sind unveränderlich: update_examinee kann E-Mail, Team oder examineeId nicht ändern (sie bilden die Authentifizierungsidentität).
  • Personenbezogene Daten werden maskiert zurückgegeben: Die Tools für Leads, Buchungen, Teilnehmer und Einsendungen geben Namen, E-Mail-Adressen und Telefonnummern maskiert zurück – auch E-Mail-Adressen und Telefonnummern, die in Antworten eingegeben wurden. Die Maskierung ist nicht umkehrbar; verweisen Sie auf Personen über examineeId, leadId oder die ID der Einsendung.

Sicherheit & Ratenlimits

  • Ob OAuth oder Token: Die KI handelt als Sie und löst die bestehenden Zugriffsprüfungen und Audit-Logs aus (jeder Schreibvorgang wird erfasst).
  • Jede Verbindung ist auf 60 Anfragen / Minute begrenzt; bei Überschreitung wird ein Ratenlimit-Fehler zurückgegeben.
  • Wenn sie nicht mehr benötigt wird, widerrufen Sie sie (wirkt sofort; bei OAuth-Verbindungen wird der Client getrennt) oder löschen Sie sie (gibt zusätzlich einen Platz frei) unter Einstellungen → MCP-Integration.
  • Der OAuth-Ablauf erzwingt PKCE (S256), Autorisierungscodes sind nur einmal verwendbar, und Refresh-Tokens werden bei jeder Erneuerung rotiert – alte werden sofort ungültig.

Auf dieser Seite