RooQuiz Docs
Integraciones y API

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:

  1. Ponle un Nombre del token (para reconocerlo, p. ej. Cursor - my Mac).
  2. 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.
  3. 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)

HerramientaQué hace
list_my_tenantsLista todos los equipos de los que formas parte y marca el que está activo.
get_active_tenantDevuelve el equipo activo del token (incluida su dirección de equipo); todas las escrituras se dirigen a él de forma predeterminada.
switch_active_tenantCambia el equipo activo (se mantiene entre sesiones; el destino debe ser un equipo al que te hayas unido).
invite_memberInvita 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_slugCambia 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

HerramientaQué hace
list_templatesLista 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_templateCrea 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

HerramientaQué hace
create_formCrea 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_formsLista los quizzes del equipo actual, de más reciente a más antiguo, sin el contenido de las preguntas.
get_formMuestra 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_formActualiza 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_formMueve 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_formRestaura desde la papelera un quiz eliminado con delete_form.
duplicate_formDuplica 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

HerramientaQué hace
get_form_share_infoTodo 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_settingsCambia 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

HerramientaQué hace
add_questionAñ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_questionInserta un elemento en una posición concreta, usando after / before para hacer referencia a un code existente.
move_questionMueve una pregunta o un salto de página existente a una nueva posición por su code.
update_questionActualiza 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_questionElimina una pregunta o un salto de página por su code.

Dimensiones del informe

HerramientaQué hace
set_dimension_analysisDefine 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).

HerramientaQué hace
create_form_translationAñ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_translationsLista las versiones de idioma existentes de un quiz (idioma, indicador de activa, enlace público, etc.).
get_form_translationLee 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_translationGuarda 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_translationElimina 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.

HerramientaQué hace
list_examineesLista los participantes del equipo actual, con búsqueda aproximada opcional por correo electrónico o nombre y filtro por estado (activo / deshabilitado).
get_examineeMuestra 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_examineeEdita 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

HerramientaQué hace
list_leadsLista 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_leadMuestra 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_settingsLee 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_leadMueve un lead a otro estado de seguimiento (p. ej. nuevo → contactado); queda registrado en la cronología del lead.
assign_leadsAsigna 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_tagsDefine 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_commentEscribe un comentario interno de seguimiento en un lead (solo para el equipo, nunca se muestra al participante), opcionalmente vinculado a una respuesta.

Reservas

HerramientaQué hace
list_bookingsLista 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.

HerramientaQué hace
get_form_statsLee 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_funnelLee 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_recordsLista 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_recordMuestra 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

HerramientaQué hace
prepare_image_uploadPaso 1: emite una URL de subida directa para una portada o imagen (sube el archivo con PUT a esa URL).
finalize_image_uploadPaso 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 con update_form / update_question.
  • Examen / cuestionario con puntuación: create_form para crear el quiz y obtener el code de cada pregunta → usa update_form o set_dimension_analysis para configurar las fórmulas o dimensiones del informe por code.
  • Cuestionario de resultado: create_form en una sola llamada con report.outcomes (da a cada tipo un code ú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 con update_form.
  • Lanzamiento: update_form_settings para definir la barrera de leads y las secciones de la página de resultados → get_form_share_info para 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_question y luego add_question para reconstruirla. Las opciones se pueden reemplazar en bloque con update_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_question rechaza score / correctAnswer / aiMatch en el nivel superior; pasa en su lugar opciones con choices[i].score (Option Scoring) o choices[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_form mueve 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_question e insert_question se rechazan al superar ese número. duplicate_form y create_form_from_template no tienen límite. Pro es ilimitado; consulta Límite de preguntas.
  • Duplicar no copia datos: duplicate_form clona 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_examinee no puede cambiar el correo electrónico, el equipo ni el examineeId (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, leadId o 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.

En esta página