RooQuiz Docs
Integrações e API

Integração MCP

O RooQuiz oferece um servidor MCP (Model Context Protocol) que permite que clientes de IA — ChatGPT, claude.ai, Claude Desktop, Claude Code, Cursor, Codex e outros — trabalhem dentro da sua equipe. Com linguagem natural, você pode criar quizzes a partir de modelos ou do zero, adicionar e editar perguntas, configurar dimensões do relatório ou tipos de resultado, alterar configurações de entrega e obter links de compartilhamento, gerenciar traduções e respondentes, trabalhar seus leads e ler agendamentos, registros de respostas, estatísticas e funis de conversão — em vez de fazer tudo manualmente no editor.

O RooQuiz não tem um gerador de quizzes por IA integrado. Para montar um quiz com IA, conecte o seu próprio cliente de IA via MCP e peça a ele — ele usa as ferramentas abaixo, e você revisa o resultado no editor.

O MCP é um recurso para usuários avançados — você precisará de um cliente de IA compatível com MCP. Para criar quizzes de forma básica e visual, continuamos recomendando o editor.

Como funciona

  • Um cliente de IA se conecta ao endpoint MCP do RooQuiz (/api/mcp) usando um de dois métodos de autenticação: autorização OAuth (recomendada — nos clientes compatíveis, basta entrar pelo navegador) ou um token de API pessoal.
  • Em ambos os casos, a IA age como você na equipe ativa no momento.
  • Cada ação passa pelas mesmas verificações de acesso do painel administrativo; as operações de escrita também são registradas no log de auditoria.
  • Assim, o que a IA pode fazer é totalmente limitado pela sua função e pelas suas permissões nessa equipe — ela não pode ultrapassá-las.

Opção 1: autorização OAuth (recomendada)

Clientes compatíveis com OAuth do MCP — ChatGPT, claude.ai e Claude Code — não precisam de um token criado manualmente. Basta informar a URL do endpoint: o cliente descobre o servidor de autorização automaticamente e abre o navegador, onde você entra no RooQuiz, escolhe a equipe a autorizar e clica em "Autorizar".

O RooQuiz está disponível como app no ChatGPT. Clique em Usar no ChatGPT no topo do painel administrativo do RooQuiz para abri-lo e conecte — o navegador é redirecionado para a página de autorização do RooQuiz; entre, escolha uma equipe e clique em "Autorizar".

Sobre as conexões OAuth:

  • A equipe escolhida durante a autorização passa a ser a equipe ativa inicial; a IA ainda pode trocar depois com switch_active_tenant.
  • A conexão aparece na lista de tokens em Configurações → Integração MCP (com a marcação OAuth); revogá-la desconecta esse cliente. Ela não conta para o limite de 5 tokens.
  • As credenciais são renovadas automaticamente (o token de acesso é atualizado a cada 1 hora de forma contínua; a conexão em si é válida por 30 dias e se estende com o uso) — não há nada para manter manualmente.

Opção 2: token pessoal (PAT)

Para clientes sem suporte a OAuth (Cursor, Codex CLI, Claude Desktop) ou ambientes sem navegador, como CI, conecte-se com um token de API pessoal.

Crie um token

Acesse Configurações → Integração MCP e clique em Criar token:

  1. Dê a ele um Nome do token (para identificá-lo, por exemplo Cursor - my Mac).
  2. Escolha um Time inicial — o token opera nessa equipe por padrão, e a IA pode depois trocar para qualquer outra equipe de que você faça parte pela ferramenta switch_active_tenant.
  3. Após a criação, é exibido um token em texto simples que começa com rqp_live_.

O token em texto simples é exibido apenas uma vez. Ele não pode ser recuperado depois que você sai da página. Copie-o imediatamente; se perdê-lo, será necessário revogá-lo e criar um novo.

Limites:

  • Cada usuário pode ter no máximo 5 tokens (incluindo os revogados; conexões OAuth não contam). Para criar mais, exclua um para liberar espaço ("revogar" apenas desativa — não libera o espaço). Um token pessoal revogado pode ser reativado com Ativar.
  • Um token é uma credencial pessoal — nunca o inclua no controle de versão nem o compartilhe publicamente.

Configure seu cliente de IA

Na página Configurações → Integração MCP, você pode copiar trechos de configuração prontos para cada cliente, junto com a sua URL do endpoint (algo como https://your-domain/api/mcp). Substitua rqp_live_xxx... no trecho pelo token que você acabou de gerar.

No Claude Code, prefira o fluxo OAuth acima; o cabeçalho de token só é necessário em ambientes sem navegador, como CI:

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

Exemplos de prompts

Depois de conectar o cliente, converse com ele em linguagem simples. Cada um destes exemplos usa uma parte diferente do servidor:

Criar a partir de um modelo

Mostre os modelos de coaching, crie um quiz com pontuação a partir do modelo de prontidão e depois adicione duas perguntas sobre orçamento.

Usa list_templates → create_form_from_template → add_question.

Trabalhar os leads

Liste os leads que meu quiz Roda da Vida captou nesta semana, marque todos que pontuaram abaixo de 40 com a tag follow-up e atribua-os a mim.

Usa list_leads → set_lead_tags → assign_leads.

Diagnosticar o funil

Qual dos meus quizzes tem a pior taxa de conclusão e em que ponto exatamente as pessoas desistem?

Usa list_forms → get_form_stats → get_form_funnel.

Tornar multilíngue

Traduza meu quiz de prontidão para promoção para espanhol e alemão, mantendo os códigos das perguntas.

Usa list_form_translations → create_form_translation.

Nomes, endereços de e-mail e números de telefone dos respondentes retornam mascarados (j***g@example.com). O mascaramento é irreversível, então faça referência a um respondente pelo id em vez de colar um valor mascarado de volta em um prompt.

Ferramentas disponíveis

Depois de conectado, o assistente de IA pode chamar as 44 ferramentas abaixo. Todas atuam na equipe em que o token está ativo no momento.

Equipe (Tenant)

FerramentaO que faz
list_my_tenantsLista todas as equipes de que você faz parte, marcando a ativa no momento.
get_active_tenantRetorna a equipe em que o token está ativo no momento (incluindo o endereço da equipe); todas as escritas usam essa equipe por padrão.
switch_active_tenantTroca a equipe ativa (persiste entre sessões; o destino deve ser uma equipe de que você participa).
invite_memberConvida alguém por e-mail para a equipe ativa como membro ou administrador; é enviado um e-mail de convite com um link de entrada. Somente proprietário / administrador.
update_tenant_slugAltera o endereço da equipe — o primeiro segmento do caminho de todo link de quiz no domínio da plataforma. Somente proprietário / administrador. Todos os links públicos de quiz mudam de uma vez e o endereço antigo deixa de funcionar; links /a/<token> continuam funcionando.

Modelos

FerramentaO que faz
list_templatesLista os modelos ativos da biblioteca pública de modelos (título, cenário, descrição, categoria, número de usos), dos mais usados para os menos usados.
create_form_from_templateCria um novo quiz a partir de um modelo em uma única chamada: estrutura, configuração de pontuação / relatório, configurações visuais e todas as versões de idioma. A forma mais rápida de montar um quiz quando existe um modelo adequado.

Formulário

FerramentaO que faz
create_formCria um quiz (knowledge_quiz, scored_quiz ou outcome_quiz de perfil). Pode receber um array de perguntas e a configuração do relatório em uma única chamada para evitar idas e voltas. Um quiz de resultado deve incluir report.outcomes (a lista de tipos de resultado) na criação, com cada opção votando em tipos via outcomes.
list_formsLista os quizzes da equipe atual, dos mais recentes para os mais antigos, sem o conteúdo das perguntas.
get_formMostra os detalhes completos de um quiz (a lista de perguntas fields[], a configuração do relatório etc.); chame esta ferramenta primeiro para obter o code de cada pergunta antes de editar — nos quizzes de resultado, os codes dos tipos de resultado ficam em report.outcomeAnalysis.outcomes.
update_formAtualiza título, descrição, estado aberto/fechado, capas (flagImg / landingImage), tema, cartão de compartilhamento social (openGraph), textos do sistema, ou substitui por mesclagem a configuração report por subchave; nos quizzes de resultado, passe report.outcomes para atualizar por mesclagem os tipos de resultado por code (imagens já configuradas são mantidas, e remover um tipo ainda referenciado por votos de perguntas é rejeitado). O idioma só pode ser alterado enquanto o quiz não tiver versões de idioma; o cenário, nunca.
delete_formMove um quiz para a lixeira (exclusão lógica): fica oculto em list_forms e pode ser recuperado por 5 dias via restore_form (depois é removido permanentemente). Qualquer membro da equipe pode excluir; os registros de respostas são mantidos até a remoção permanente.
restore_formRestaura da lixeira um quiz excluído por delete_form.
duplicate_formDuplica um quiz: clona a estrutura de perguntas, a pontuação, o relatório, o visual e as configurações, além de todas as traduções, em um novo quiz de sua propriedade (com links novos). Não copia registros de respostas, integrações nem estado de bloqueio. newTitle opcional.

Compartilhamento e configurações de entrega

FerramentaO que faz
get_form_share_infoTudo o que é preciso para publicar um quiz: o link público de resposta (também por versão de idioma), o domínio personalizado da equipe e se ele está ativo, trechos de incorporação em três modos (inline / popup / iframe) e as configurações de entrega atuais. Passe utmSource para marcar todos os links e trechos para um canal.
update_form_settingsAltera como um quiz é entregue: quem pode responder e se o relatório exige um e-mail (a barreira de captação de leads) e um código de verificação, tempo limite (quizzes de conhecimento), compartilhamento e cartão de compartilhamento, folha de respostas, comparação com outros respondentes, a seção de agendamento da página de resultados e seu link do Cal.com, o bloco de feedback, download em PDF (Pro), ID do Google Analytics e mais.

Pergunta

FerramentaO que faz
add_questionAdiciona um item ao final: uma pergunta, uma quebra de página (Breaker) ou um bloco de exibição (Statement, trecho de rich text; Swiper, carrossel de imagens). Tipos de pergunta: SingleCheck / MultiCheck / TrueFalse, FillBlank, DropDown, Ordering (quiz de conhecimento), NumberField e Rate (quiz com pontuação). Em um quiz de resultado, cada opção deve declarar em quais tipos de resultado vota (TrueFalse usa trueOutcomes / falseOutcomes).
insert_questionInsere um item em uma posição específica, usando after / before para referenciar um code existente.
move_questionMove uma pergunta ou quebra de página existente para uma nova posição por code.
update_questionAtualiza uma pergunta por code: enunciado, nota, explicação, obrigatoriedade, pontuação, resposta correta, correção por IA de FillBlank, opções de número / data / avaliação, ou substitui todas as opções de uma pergunta de escolha. Os blocos de exibição também são editados aqui. Não pode alterar o tipo da pergunta.
delete_questionExclui uma pergunta ou quebra de página por code.

Dimensões do relatório

FerramentaO que faz
set_dimension_analysisDefine de uma vez a análise multidimensional de um quiz (as dimensões do gráfico de radar); só scored_quiz tem dimensões, e cada uma usa uma fórmula sobre codes de perguntas (quizzes de conhecimento não têm dimensões). Passe um array vazio para limpar. Não se aplica a quizzes de resultado (eles não têm dimensões — configure os tipos de resultado via report.outcomes).

Traduções (FormTranslation)

Ofereça um quiz em vários idiomas: um quiz de origem (idioma principal) mais uma tradução para cada outro idioma (mesma estrutura da origem, apenas o texto é traduzido; os registros de respostas sempre ficam vinculados ao quiz de origem).

FerramentaO que faz
create_form_translationAdiciona uma versão de idioma a um quiz, clonando o texto de origem como rascunho inicial (mesmos codes, texto no idioma de origem), e retorna esse conteúdo para traduzir imediatamente. O idioma deve ser diferente do principal, no máximo uma versão por idioma.
list_form_translationsLista as versões de idioma existentes de um quiz (idioma, indicador de ativo, link público etc.).
get_form_translationLê o conteúdo completo de uma versão de idioma (incluindo fields[] e report) para traduzir no lugar — cada code deve permanecer idêntico ao da origem.
update_form_translationSalva o texto traduzido de uma versão de idioma (title / description / fields / report / systemText) ou a pausa via isActive; a estrutura é definida pela origem, você só altera o texto, e campos omitidos contam como tradução parcial.
delete_form_translationExclui uma versão de idioma.

Respondentes (examinandos)

As pessoas que fazem um quiz — chamadas de Respondentes no painel administrativo; as ferramentas mantêm o termo examinee. Cada examinando está vinculado a uma única equipe; as ferramentas retornam apenas campos seguros — senha, código de verificação, token de redefinição e outros campos sensíveis nunca são expostos.

FerramentaO que faz
list_examineesLista os respondentes da equipe atual, com busca aproximada opcional por e-mail / nome e filtro por status (ativo / desativado).
get_examineeMostra os detalhes de um respondente (incluindo customData personalizados) pelo ID de negócio examineeId (por exemplo, AB1234567890, exibido na lista).
update_examineeEdita nome / status / customData de um respondente por examineeId (customData é validado com base nas definições de campos da equipe e substitui o objeto inteiro). E-mail e equipe não podem ser alterados.

Leads

FerramentaO que faz
list_leadsLista os leads da equipe — um por respondente em todos os quizzes, com status de acompanhamento, responsável, tags coloridas, número de envios e próximo agendamento. Filtre por status / responsável / tags / data de criação / palavra-chave / agendamento futuro.
get_leadMostra um lead por leadId, opcionalmente com o histórico de envios do respondente, os comentários internos da equipe e a linha do tempo de alterações.
list_lead_settingsLê os status de acompanhamento, a biblioteca de tags e os membros atribuíveis da equipe. Chame antes de escrever — os códigos de status, os códigos de tag e os ids de membros são específicos de cada equipe.
update_leadMove um lead para outro status de acompanhamento (por exemplo, novo → contatado); fica registrado na linha do tempo do lead.
assign_leadsAtribui até 50 leads a um membro ativo em uma única chamada ("me" para você mesmo), ou remove o responsável. O responsável recebe uma única notificação agregada.
set_lead_tagsDefine tags coloridas em até 50 leads em uma única chamada: replace (um único lead), ou add / remove em lotes, para que as tags de outras pessoas sejam preservadas.
add_lead_commentEscreve um comentário interno de acompanhamento em um lead (só para a equipe, nunca exibido ao respondente), opcionalmente vinculado a um envio.

Agendamentos

FerramentaO que faz
list_bookingsLista os agendamentos da equipe sincronizados do Cal.com, dos mais próximos para os mais distantes, com horário, status, tipo de evento do Cal.com, participante, quiz e envio de origem e responsável pelo lead. Filtre por status / quiz / respondente / intervalo de tempo. Somente leitura — os agendamentos são alterados no Cal.com.

Registros e análises

Leia o desempenho dos quizzes e os envios para que a IA feche o ciclo criar → medir → iterar.

FerramentaO que faz
get_form_statsLê as estatísticas de um quiz nos últimos N dias (padrão 30, máx. 180): visão geral dos KPIs, tendência diária, canais (utm_source), tipos de login, dispositivos e distribuição de respostas por pergunta.
get_form_funnelLê o funil de conversão de um quiz nos últimos N dias: visualizado → iniciado → enviado → lead captado → relatório visualizado → CTA clicado → compartilhado, além do funil por canal e dos pontos de abandono.
list_recordsLista os registros de respostas da equipe atual: respondente, respostas, um resultado compacto do relatório e UTM; filtre por quiz, status do relatório e data de envio.
get_recordMostra os detalhes de um registro pelo seu id (retornado por list_records): respostas completas, resultado do relatório e metadados do envio.

Upload de imagens

FerramentaO que faz
prepare_image_uploadEtapa 1: gera uma URL de upload direto para uma capa/imagem (envie o arquivo para ela com PUT).
finalize_image_uploadEtapa 2: verifica e registra a imagem na biblioteca de mídia da equipe, retornando um id de mídia; referencie-o via flagImg / landingImage de update_form.

Fluxos típicos:

  • A partir de um modelo: list_templates → create_form_from_template → ajuste com update_form / update_question.
  • Prova / quiz com pontuação: create_form para criar o quiz e obter o code de cada pergunta → use update_form ou set_dimension_analysis para configurar fórmulas / dimensões do relatório por code.
  • Outcome quiz: create_form em uma única chamada com report.outcomes (dê a cada tipo um code único definido por você, por exemplo lion) mais os votos de cada opção → após o envio, vence o tipo com mais votos (empates resolvidos pela ordem da lista); ajuste depois os textos / CTAs dos tipos via update_form.
  • Lançamento: update_form_settings para definir a barreira de leads e as seções da página de resultados → get_form_share_info para obter o link e o código de incorporação.

Limitações atuais

  • O tipo da pergunta não pode ser alterado: para trocar o tipo, use delete_question e depois add_question para recriar. As opções podem ser substituídas por inteiro com update_question, mas os votos de resultado de TrueFalse (trueOutcomes / falseOutcomes) ainda exigem excluir e recriar.
  • Pontuação específica de cada cenário: nos cenários de quiz com pontuação e de quiz de resultado, update_question rejeita score / correctAnswer / aiMatch no nível superior — passe opções com choices[i].score (Pontuação por opção) ou choices[i].outcomes (votos).
  • Tipos de pergunta por cenário: Ordering é exclusivo do quiz de conhecimento; Rate é exclusivo do quiz com pontuação; FillBlank em um quiz com pontuação apenas coleta dados; quizzes de resultado aceitam SingleCheck / MultiCheck / DropDown / TrueFalse (além de quebras de página e blocos de exibição).
  • Imagens de resultado: as imagens dos tipos de resultado ainda não podem ser enviadas via MCP — configure-as no editor (imagens já configuradas são mantidas quando o MCP atualiza report.outcomes).
  • O cenário fica bloqueado após a criação; o idioma só pode ser alterado enquanto o quiz não tiver versões de idioma.
  • A exclusão é lógica: delete_form move para a lixeira (removido automaticamente após 5 dias), não é uma exclusão permanente imediata; para remoção permanente, exclua novamente no painel administrativo.
  • Limite de perguntas: no plano Free, um quiz comporta no máximo 50 perguntas (quebras de página, blocos de rich text e carrosséis de imagens não contam); create_form, add_question e insert_question são rejeitados acima disso. duplicate_form e create_form_from_template não têm limite. O Pro é ilimitado — consulte Limite de perguntas.
  • A duplicação não copia dados: duplicate_form clona apenas a estrutura e as traduções — não copia registros de respostas nem integrações (que contêm segredos); o novo quiz começa limpo.
  • Os campos de identidade do respondente são imutáveis: update_examinee não pode alterar e-mail, equipe ou examineeId (eles são a identidade de autenticação).
  • Os dados pessoais retornam mascarados: as ferramentas de leads, agendamentos, respondentes e registros retornam nomes, endereços de e-mail e números de telefone mascarados — incluindo e-mails e telefones digitados nas respostas. O mascaramento é irreversível; faça referência às pessoas por examineeId, leadId ou id do registro.

Segurança e limites de taxa

  • Com OAuth ou token, a IA age como você, acionando as verificações de acesso existentes e os logs de auditoria (toda escrita é registrada).
  • Cada conexão está limitada a 60 requisições / minuto; ao exceder esse limite, é retornado um erro de limite de taxa.
  • Quando não for mais necessário, revogue (tem efeito imediato; nas conexões OAuth, isso desconecta o cliente) ou exclua (também libera espaço) em Configurações → Integração MCP.
  • O fluxo OAuth exige PKCE (S256), os códigos de autorização são de uso único e os refresh tokens são rotacionados a cada renovação — os antigos se tornam inválidos imediatamente.

Nesta página