Integración MCP
RooQuiz incluye un servidor MCP (Model Context Protocol) que permite a los clientes de AI (ChatGPT, claude.ai, Claude Desktop, Claude Code, Cursor, Codex y otros) trabajar dentro de tu equipo. Con lenguaje natural puedes crear quizzes a partir de plantillas o desde cero, añadir y editar preguntas, configurar las dimensiones del informe o los tipos de resultado, cambiar la configuración de entrega y obtener enlaces para compartir, gestionar traducciones y participantes, trabajar tus leads, y consultar reservas, registros de respuestas, estadísticas y embudos de conversión, en lugar de hacerlo todo a mano en el editor.
RooQuiz no tiene un generador de quizzes con AI integrado. Para crear un quiz con AI, conecta tu propio cliente de AI mediante MCP y pídeselo: usará las herramientas que se describen más abajo, y tú revisas el resultado en el editor.
MCP es una función para usuarios avanzados: necesitarás un cliente de AI compatible con MCP. Para crear quizzes de forma visual y sencilla, seguimos recomendando el editor.
Cómo funciona
- Un cliente de AI se conecta al endpoint MCP de RooQuiz (
/api/mcp) con uno de estos dos métodos de autenticación: autorización OAuth (recomendado: los clientes compatibles solo tienen que iniciar sesión en el navegador) o un token de API personal. - En ambos casos, la AI actúa en tu nombre dentro del equipo activo en ese momento.
- Cada acción pasa por las mismas comprobaciones de acceso que la interfaz de administración; las operaciones de escritura también quedan registradas en el registro de auditoría.
- Por tanto, lo que la AI puede hacer está limitado por completo por tu rol y tus permisos en ese equipo: no puede excederlos.
Opción 1: autorización OAuth (recomendada)
Los clientes compatibles con MCP OAuth (ChatGPT, claude.ai y Claude Code) no necesitan que crees un token a mano. Basta con indicar la URL del endpoint: el cliente detecta automáticamente el servidor de autorización y abre tu navegador, donde inicias sesión en RooQuiz, eliges el equipo que quieres autorizar y haces clic en «Autorizar».
RooQuiz está disponible como app en ChatGPT. Haz clic en Usar en ChatGPT, en la parte superior del panel de administración de RooQuiz, para abrirla y luego conéctate: el navegador te redirige a la página de autorización de RooQuiz; inicia sesión, elige un equipo y haz clic en «Autorizar».
Sobre las conexiones OAuth:
- El equipo que eliges durante la autorización pasa a ser el equipo activo inicial; la AI puede cambiarlo más adelante con
switch_active_tenant. - La conexión aparece en la lista de tokens de Ajustes → Integración MCP (con la etiqueta OAuth); revocarla desconecta ese cliente. No cuenta para el límite de 5 tokens.
- Las credenciales se renuevan automáticamente (el token de acceso se actualiza de forma continua cada hora; la conexión sigue siendo válida durante 30 días y se prolonga con el uso): no hay nada que mantener a mano.
Opción 2: token personal (PAT)
Para clientes sin compatibilidad con OAuth (Cursor, Codex CLI, Claude Desktop) o entornos sin navegador como CI, conéctate con un token de API personal.
Crear un token
Ve a Ajustes → Integración MCP y haz clic en Crear token:
- Ponle un Nombre del token (para reconocerlo, p. ej.
Cursor - my Mac). - Elige un Equipo inicial: el token trabaja con este equipo de forma predeterminada, y la AI puede cambiar después a cualquier otro equipo del que formes parte con la herramienta
switch_active_tenant. - Tras crearlo, se muestra un token en texto plano que empieza por
rqp_live_.
El token en texto plano solo se muestra una vez. No se puede recuperar después de salir de la página. Cópialo de inmediato; si lo pierdes, tendrás que revocarlo y crear uno nuevo.
Límites:
- Cada usuario puede tener como máximo 5 tokens (incluidos los revocados; las conexiones OAuth no cuentan). Para crear más, elimina uno y así liberarás un hueco («revocar» solo lo desactiva, no libera el hueco). Un token personal revocado puede volver a activarse con Activar.
- Un token es una credencial personal: nunca lo incluyas en el control de versiones ni lo compartas públicamente.
Configurar tu cliente de AI
En la página Ajustes → Integración MCP puedes copiar fragmentos de configuración listos para cada cliente, junto con tu URL del endpoint (con un aspecto como https://your-domain/api/mcp). Sustituye rqp_live_xxx... en el fragmento por el token que acabas de generar.
Con Claude Code, es preferible el flujo OAuth anterior; la cabecera con token solo es necesaria en entornos sin navegador como CI:
claude mcp add --transport http rooquiz https://your-domain/api/mcp \
--header "Authorization: Bearer rqp_live_xxx..."Ejemplos de instrucciones
Una vez conectado tu cliente, háblale en lenguaje natural. Cada uno de estos ejemplos pone a prueba una parte distinta del servidor:
Crear a partir de una plantilla
Muéstrame las plantillas de coaching, crea un cuestionario con puntuación a partir de la de preparación y añade dos preguntas sobre presupuesto.
Usa list_templates → create_form_from_template → add_question.
Trabajar los leads
Lista los leads que ha captado esta semana mi quiz de la Rueda de la vida, etiqueta como seguimiento a todos los que hayan sacado menos de 40 y asígnamelos.
Usa list_leads → set_lead_tags → assign_leads.
Diagnosticar el embudo
¿Cuál de mis quizzes tiene la peor tasa de finalización y en qué punto exacto abandona la gente?
Usa list_forms → get_form_stats → get_form_funnel.
Pasar a varios idiomas
Traduce mi quiz de preparación para un ascenso al español y al alemán, manteniendo los códigos de las preguntas.
Usa list_form_translations → create_form_translation.
Los nombres, correos electrónicos y teléfonos de los participantes se devuelven enmascarados
(j***g@example.com). El enmascaramiento es irreversible, así que refiérete a un participante por su id en lugar de
pegar un valor enmascarado de nuevo en una instrucción.
Herramientas disponibles
Una vez conectado, el asistente de AI puede llamar a las 44 herramientas siguientes. Todas actúan sobre el equipo que está activo en ese momento para el token.
Equipo (Tenant)
| Herramienta | Qué hace |
|---|---|
list_my_tenants | Lista todos los equipos de los que formas parte y marca el que está activo. |
get_active_tenant | Devuelve el equipo activo del token (incluida su dirección de equipo); todas las escrituras se dirigen a él de forma predeterminada. |
switch_active_tenant | Cambia el equipo activo (se mantiene entre sesiones; el destino debe ser un equipo al que te hayas unido). |
invite_member | Invita por correo electrónico a alguien al equipo activo como miembro o administrador; se envía un correo de invitación con un enlace para unirse. Solo propietario / administrador. |
update_tenant_slug | Cambia la dirección del equipo, el primer segmento de la ruta de cada enlace de quiz en el dominio de la plataforma. Solo propietario / administrador. Todos los enlaces públicos de quiz cambian a la vez y la dirección anterior deja de funcionar; los enlaces /a/<token> siguen funcionando. |
Plantillas
| Herramienta | Qué hace |
|---|---|
list_templates | Lista las plantillas activas de la biblioteca pública de plantillas (título, escenario, descripción, categoría, número de usos), de más a menos usadas. |
create_form_from_template | Crea un quiz nuevo a partir de una plantilla en una sola llamada: estructura, configuración de puntuación / informe, ajustes visuales y todas las versiones de idioma. Es la forma más rápida de crear un quiz cuando existe una plantilla adecuada. |
Formulario
| Herramienta | Qué hace |
|---|---|
create_form | Crea un quiz (knowledge_quiz, scored_quiz o quiz de tipología outcome_quiz). Puede recibir un array de preguntas y la configuración del informe en una sola llamada para evitar idas y vueltas. Un cuestionario de resultado debe incluir report.outcomes (la lista de tipos de resultado) al crearse, y cada opción debe votar por tipos mediante outcomes. |
list_forms | Lista los quizzes del equipo actual, de más reciente a más antiguo, sin el contenido de las preguntas. |
get_form | Muestra todos los detalles de un quiz (la lista de preguntas fields[], la configuración del informe, etc.); llámala primero para obtener el code de cada pregunta antes de editar. En los cuestionarios de resultado, los code de los tipos de resultado están en report.outcomeAnalysis.outcomes. |
update_form | Actualiza el título, la descripción, el estado abierto/cerrado, las portadas (flagImg / landingImage), el tema, la tarjeta para compartir en redes (openGraph), los textos del sistema, o reemplaza fusionando la configuración de report por subclave; en los cuestionarios de resultado, pasa report.outcomes para actualizar fusionando los tipos de resultado por code (las imágenes configuradas se conservan, y se rechaza eliminar un tipo al que todavía votan preguntas). El idioma solo se puede cambiar mientras el quiz no tenga versiones de idioma; el escenario, nunca. |
delete_form | Mueve un quiz a la papelera (eliminación lógica): se oculta de list_forms y puede recuperarse durante 5 días con restore_form (después se purga definitivamente). Cualquier miembro del equipo puede eliminarlo; los registros de respuestas se conservan hasta la purga definitiva. |
restore_form | Restaura desde la papelera un quiz eliminado con delete_form. |
duplicate_form | Duplica un quiz: clona su estructura de preguntas, puntuación, informe, apariencia y configuración, además de todas las traducciones, en un nuevo quiz del que eres propietario (con enlaces nuevos). No copia los registros de respuestas, las integraciones ni el estado de bloqueo. newTitle es opcional. |
Compartir y configuración de entrega
| Herramienta | Qué hace |
|---|---|
get_form_share_info | Todo lo necesario para publicar un quiz: el enlace público para responder (también por versión de idioma), el dominio personalizado del equipo y si está activo, fragmentos de inserción en tres modos (inline / popup / iframe) y la configuración de entrega actual. Pasa utmSource para etiquetar todos los enlaces y fragmentos para un canal. |
update_form_settings | Cambia cómo se entrega un quiz: quién puede responder y si el informe exige un correo (la barrera de captación de leads) y un código de verificación, límite de tiempo (cuestionarios de conocimiento), compartir y tarjeta para compartir, hoja de respuestas, comparación con el grupo, la sección de reservas de la página de resultados y su enlace de Cal.com, el bloque de comentarios, la descarga en PDF (Pro), el ID de Google Analytics y más. |
Pregunta
| Herramienta | Qué hace |
|---|---|
add_question | Añade un elemento al final: una pregunta, un salto de página (Breaker) o un bloque de presentación (Statement, pasaje de texto enriquecido; Swiper, carrusel de imágenes). Tipos de pregunta: SingleCheck / MultiCheck / TrueFalse, FillBlank, DropDown, Ordering (cuestionario de conocimiento), NumberField y Rate (cuestionario con puntuación). En un cuestionario de resultado, cada opción debe declarar por qué tipos de resultado vota (TrueFalse usa trueOutcomes / falseOutcomes). |
insert_question | Inserta un elemento en una posición concreta, usando after / before para hacer referencia a un code existente. |
move_question | Mueve una pregunta o un salto de página existente a una nueva posición por su code. |
update_question | Actualiza una pregunta por code: enunciado, nota, explicación, indicador de obligatoria, puntuación, respuesta correcta, corrección con AI de FillBlank, opciones de número / fecha / valoración, o reemplaza todas las opciones de una pregunta de elección. Los bloques de presentación también se editan aquí. No puede cambiar el tipo de pregunta. |
delete_question | Elimina una pregunta o un salto de página por su code. |
Dimensiones del informe
| Herramienta | Qué hace |
|---|---|
set_dimension_analysis | Define en bloque el análisis multidimensional de un quiz (las dimensiones del gráfico de radar); solo scored_quiz tiene dimensiones, y cada una usa una fórmula sobre codes de preguntas (los cuestionarios de conocimiento no tienen dimensiones). Pasa un array vacío para borrarlo. No se aplica a los cuestionarios de resultado (no tienen dimensiones: configura los tipos de resultado con report.outcomes). |
Traducciones (FormTranslation)
Ofrece un quiz en varios idiomas: un quiz de origen (idioma principal) más una traducción por cada idioma adicional (con la misma estructura que el origen, solo se traduce el texto; los registros de respuestas siempre se asocian al quiz de origen).
| Herramienta | Qué hace |
|---|---|
create_form_translation | Añade una versión de idioma a un quiz, clonando el contenido de origen como borrador inicial (mismos codes, texto en el idioma de origen), y devuelve ese contenido para traducirlo de inmediato. El idioma debe ser distinto del principal, y solo puede haber una versión por idioma. |
list_form_translations | Lista las versiones de idioma existentes de un quiz (idioma, indicador de activa, enlace público, etc.). |
get_form_translation | Lee el contenido completo de una versión de idioma (incluidos fields[] y report) para traducirlo en el mismo lugar; cada code debe mantenerse idéntico al del origen. |
update_form_translation | Guarda el texto traducido de una versión de idioma (title / description / fields / report / systemText) o la pausa mediante isActive; la estructura la fija el origen, solo cambias el texto, y los campos omitidos cuentan como traducción parcial. |
delete_form_translation | Elimina una versión de idioma. |
Participantes (examinees)
Las personas que responden un quiz; en la interfaz de administración se llaman Participantes, y las herramientas mantienen el término examinee. Cada participante está vinculado a un único equipo; las herramientas solo devuelven campos seguros: la contraseña, el código de verificación, el token de restablecimiento y otros campos sensibles nunca se exponen.
| Herramienta | Qué hace |
|---|---|
list_examinees | Lista los participantes del equipo actual, con búsqueda aproximada opcional por correo electrónico o nombre y filtro por estado (activo / deshabilitado). |
get_examinee | Muestra el detalle de un participante (incluido su customData personalizado) a partir de su ID de negocio examineeId (p. ej. AB1234567890, visible en la lista). |
update_examinee | Edita el nombre, el estado o el customData de un participante por examineeId (el customData se valida con las definiciones de campos del equipo y reemplaza el objeto completo). El correo electrónico y el equipo no se pueden cambiar. |
Leads
| Herramienta | Qué hace |
|---|---|
list_leads | Lista los leads del equipo (uno por participante en todos los quizzes) con estado de seguimiento, responsable, etiquetas de color, número de respuestas y próxima reserva. Filtra por estado / responsable / etiquetas / fecha de creación / palabra clave / reserva próxima. |
get_lead | Muestra un lead por leadId, opcionalmente con el historial de respuestas del participante, los comentarios internos del equipo y la cronología de cambios. |
list_lead_settings | Lee los estados de seguimiento, la biblioteca de etiquetas y los miembros asignables del equipo. Llámala antes de escribir: los códigos de estado, los códigos de etiqueta y los ids de miembro son propios de cada equipo. |
update_lead | Mueve un lead a otro estado de seguimiento (p. ej. nuevo → contactado); queda registrado en la cronología del lead. |
assign_leads | Asigna hasta 50 leads a un miembro activo en una sola llamada ("me" para ti), o quita el responsable. El responsable recibe una única notificación agrupada. |
set_lead_tags | Define etiquetas de color en hasta 50 leads en una sola llamada: replace (un solo lead), o add / remove para lotes, de modo que se conserven las etiquetas de otras personas. |
add_lead_comment | Escribe un comentario interno de seguimiento en un lead (solo para el equipo, nunca se muestra al participante), opcionalmente vinculado a una respuesta. |
Reservas
| Herramienta | Qué hace |
|---|---|
list_bookings | Lista las reservas del equipo sincronizadas desde Cal.com, de la más próxima a la más lejana, con hora, estado, tipo de evento de Cal.com, asistente, quiz y respuesta de origen, y responsable del lead. Filtra por estado / quiz / participante / intervalo de tiempo. Solo lectura: las reservas se cambian en Cal.com. |
Registros y análisis
Consulta el rendimiento de los quizzes y las respuestas para que la AI pueda cerrar el ciclo crear → medir → iterar.
| Herramienta | Qué hace |
|---|---|
get_form_stats | Lee las estadísticas de un quiz de los últimos N días (30 de forma predeterminada, máximo 180): resumen de KPI, tendencia diaria, canales (utm_source), tipos de inicio de sesión, dispositivos y distribución de respuestas por pregunta. |
get_form_funnel | Lee el embudo de conversión de un quiz de los últimos N días: visto → iniciado → enviado → lead captado → informe visto → CTA pulsado → compartido, además del embudo por canal y los puntos de abandono. |
list_records | Lista los registros de respuestas del equipo actual: participante, respuestas, un resultado compacto del informe y UTM; filtra por quiz, estado del informe y fecha de envío. |
get_record | Muestra el detalle de un registro por su id (devuelto por list_records): respuestas completas, resultado del informe y metadatos del envío. |
Subida de imágenes
| Herramienta | Qué hace |
|---|---|
prepare_image_upload | Paso 1: emite una URL de subida directa para una portada o imagen (sube el archivo con PUT a esa URL). |
finalize_image_upload | Paso 2: verifica y registra la imagen en la biblioteca multimedia del equipo y devuelve un id de recurso; haz referencia a él mediante flagImg / landingImage de update_form. |
Flujos habituales:
- Desde una plantilla:
list_templates→create_form_from_template→ ajusta conupdate_form/update_question. - Examen / cuestionario con puntuación:
create_formpara crear el quiz y obtener elcodede cada pregunta → usaupdate_formoset_dimension_analysispara configurar las fórmulas o dimensiones del informe porcode. - Cuestionario de resultado:
create_formen una sola llamada conreport.outcomes(da a cada tipo uncodeúnico propio, p. ej.lion) más los votos de cada opción → tras el envío gana el tipo con más votos (los empates se resuelven por el orden de la lista); ajusta después los textos o CTA de los tipos conupdate_form. - Lanzamiento:
update_form_settingspara definir la barrera de leads y las secciones de la página de resultados →get_form_share_infopara obtener el enlace y el código de inserción.
Limitaciones actuales
- El tipo de pregunta no se puede cambiar: para cambiar el tipo, usa
delete_questiony luegoadd_questionpara reconstruirla. Las opciones se pueden reemplazar en bloque conupdate_question, pero los votos de resultado de TrueFalse (trueOutcomes/falseOutcomes) siguen requiriendo eliminar y volver a crear. - Puntuación según el escenario: en los escenarios de cuestionario con puntuación y de resultado,
update_questionrechazascore/correctAnswer/aiMatchen el nivel superior; pasa en su lugar opciones conchoices[i].score(Option Scoring) ochoices[i].outcomes(votos). - Tipos de pregunta por escenario: Ordering es exclusivo del cuestionario de conocimiento; Rate es exclusivo del cuestionario con puntuación; FillBlank en un cuestionario con puntuación solo recopila datos; los cuestionarios de resultado aceptan SingleCheck / MultiCheck / DropDown / TrueFalse (además de saltos de página y bloques de presentación).
- Imágenes de resultado: las imágenes de los tipos de resultado todavía no se pueden subir mediante MCP: configúralas en el editor (las imágenes ya configuradas se conservan cuando MCP actualiza
report.outcomes). - El escenario queda fijado tras la creación; el idioma solo se puede cambiar mientras el quiz no tenga versiones de idioma.
- La eliminación es lógica:
delete_formmueve el quiz a la papelera (se purga automáticamente a los 5 días), no lo elimina definitivamente al instante; para eliminarlo de forma permanente, vuelve a eliminarlo en la interfaz de administración. - Límite de preguntas: en el plan Free, un quiz admite como máximo 50 preguntas (los saltos de página, los bloques de texto enriquecido y los carruseles de imágenes no cuentan);
create_form,add_questioneinsert_questionse rechazan al superar ese número.duplicate_formycreate_form_from_templateno tienen límite. Pro es ilimitado; consulta Límite de preguntas. - Duplicar no copia datos:
duplicate_formclona solo la estructura y las traducciones; no copia los registros de respuestas ni las integraciones (que contienen secretos). El nuevo quiz empieza limpio. - Los campos de identidad del participante son inmutables:
update_examineeno puede cambiar el correo electrónico, el equipo ni elexamineeId(son la identidad de autenticación). - Los datos personales se devuelven enmascarados: las herramientas de leads, reservas, participantes y registros devuelven nombres, direcciones de correo y números de teléfono enmascarados, incluidos los correos y teléfonos escritos en las respuestas. El enmascaramiento es irreversible; refiérete a las personas por
examineeId,leadIdo el id del registro.
Seguridad y límites de solicitudes
- Ya sea con OAuth o con token, la AI actúa en tu nombre, activando las comprobaciones de acceso existentes y los registros de auditoría (cada escritura queda registrada).
- Cada conexión está limitada a 60 solicitudes por minuto; si se supera, se devuelve un error de límite de solicitudes.
- Cuando ya no lo necesites, revócalo (surte efecto de inmediato; en las conexiones OAuth, desconecta el cliente) o elimínalo (además libera un hueco) en Ajustes → Integración MCP.
- El flujo OAuth exige PKCE (S256), los códigos de autorización son de un solo uso y los tokens de actualización rotan en cada renovación: los antiguos dejan de ser válidos de inmediato.
Descripción general
Para desarrolladores: accede a RooQuiz desde tu propio código o desde un cliente de AI. La API REST de solo lectura obtiene formularios y respuestas, y el servidor MCP permite que tu propia AI cree quizzes, gestione leads y consulte reservas.
API REST
Una pequeña API REST de solo lectura que devuelve como JSON las definiciones de formularios de tu equipo y las respuestas recopiladas (puntuaciones, leads, UTM) para scripts, automatizaciones con Zapier/Make/n8n o paneles.