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:
- Dê a ele um Nome do token (para identificá-lo, por exemplo
Cursor - my Mac). - 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. - 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)
| Ferramenta | O que faz |
|---|---|
list_my_tenants | Lista todas as equipes de que você faz parte, marcando a ativa no momento. |
get_active_tenant | Retorna 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_tenant | Troca a equipe ativa (persiste entre sessões; o destino deve ser uma equipe de que você participa). |
invite_member | Convida 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_slug | Altera 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
| Ferramenta | O que faz |
|---|---|
list_templates | Lista 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_template | Cria 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
| Ferramenta | O que faz |
|---|---|
create_form | Cria 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_forms | Lista os quizzes da equipe atual, dos mais recentes para os mais antigos, sem o conteúdo das perguntas. |
get_form | Mostra 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_form | Atualiza 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_form | Move 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_form | Restaura da lixeira um quiz excluído por delete_form. |
duplicate_form | Duplica 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
| Ferramenta | O que faz |
|---|---|
get_form_share_info | Tudo 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_settings | Altera 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
| Ferramenta | O que faz |
|---|---|
add_question | Adiciona 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_question | Insere um item em uma posição específica, usando after / before para referenciar um code existente. |
move_question | Move uma pergunta ou quebra de página existente para uma nova posição por code. |
update_question | Atualiza 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_question | Exclui uma pergunta ou quebra de página por code. |
Dimensões do relatório
| Ferramenta | O que faz |
|---|---|
set_dimension_analysis | Define 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).
| Ferramenta | O que faz |
|---|---|
create_form_translation | Adiciona 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_translations | Lista as versões de idioma existentes de um quiz (idioma, indicador de ativo, link público etc.). |
get_form_translation | Lê 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_translation | Salva 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_translation | Exclui 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.
| Ferramenta | O que faz |
|---|---|
list_examinees | Lista os respondentes da equipe atual, com busca aproximada opcional por e-mail / nome e filtro por status (ativo / desativado). |
get_examinee | Mostra os detalhes de um respondente (incluindo customData personalizados) pelo ID de negócio examineeId (por exemplo, AB1234567890, exibido na lista). |
update_examinee | Edita 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
| Ferramenta | O que faz |
|---|---|
list_leads | Lista 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_lead | Mostra 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_settings | Lê 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_lead | Move um lead para outro status de acompanhamento (por exemplo, novo → contatado); fica registrado na linha do tempo do lead. |
assign_leads | Atribui 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_tags | Define 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_comment | Escreve um comentário interno de acompanhamento em um lead (só para a equipe, nunca exibido ao respondente), opcionalmente vinculado a um envio. |
Agendamentos
| Ferramenta | O que faz |
|---|---|
list_bookings | Lista 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.
| Ferramenta | O que faz |
|---|---|
get_form_stats | Lê 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_funnel | Lê 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_records | Lista 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_record | Mostra 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
| Ferramenta | O que faz |
|---|---|
prepare_image_upload | Etapa 1: gera uma URL de upload direto para uma capa/imagem (envie o arquivo para ela com PUT). |
finalize_image_upload | Etapa 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 comupdate_form/update_question. - Prova / quiz com pontuação:
create_formpara criar o quiz e obter ocodede cada pergunta → useupdate_formouset_dimension_analysispara configurar fórmulas / dimensões do relatório porcode. - Outcome quiz:
create_formem uma única chamada comreport.outcomes(dê a cada tipo umcodeúnico definido por você, por exemplolion) 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 viaupdate_form. - Lançamento:
update_form_settingspara definir a barreira de leads e as seções da página de resultados →get_form_share_infopara 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_questione depoisadd_questionpara recriar. As opções podem ser substituídas por inteiro comupdate_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_questionrejeitascore/correctAnswer/aiMatchno nível superior — passe opções comchoices[i].score(Pontuação por opção) ouchoices[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_formmove 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_questioneinsert_questionsão rejeitados acima disso.duplicate_formecreate_form_from_templatenão têm limite. O Pro é ilimitado — consulte Limite de perguntas. - A duplicação não copia dados:
duplicate_formclona 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_examineenão pode alterar e-mail, equipe ouexamineeId(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,leadIdou 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.
Visão geral
Para desenvolvedores: acesse o RooQuiz pelo seu próprio código ou por um cliente de IA. A API REST somente leitura retorna formulários e respostas, e o servidor MCP permite que a sua própria IA crie quizzes, trabalhe leads e consulte agendamentos.
API REST
Uma pequena API REST somente leitura que retorna as definições dos formulários da sua equipe e as respostas coletadas — pontuações, leads e UTM — em JSON, para scripts, automações Zapier/Make/n8n ou painéis próprios.