QRetro

Conecte o Claude, o Cursor e outros clientes analíticos às suas retrospectivas por meio do Model Context Protocol

O que é MCP

O Model Context Protocol (MCP) é um padrão aberto que permite que sistemas e algoritmos externos acessem dados. O QRetro fornece um servidor MCP para que você possa consultar seus dados de retrospectiva diretamente do Claude Desktop, Cursor, VS Code e outros clientes compatíveis.

Duas formas de conectar

	Entrando com login	Token de API
O que você fornece ao cliente	Apenas o endereço https://mcp.qretro.com	Uma string de token que você mesmo cria
Para quem é indicado	Claude, Claude Code, Cursor, VS Code — qualquer coisa com um navegador à mão	Automações, CI, clientes com cabeçalho fixo
Escopo de acesso	Todas as equipes das quais você participa	Opcionalmente, uma única equipe
Excluir mensagens	Não disponível	Disponível com mcp:delete
Revogação	Configurações → Chaves de API → Aplicativos conectados	Configurações → Chaves de API

Conectar entrando com login

Forneça ao cliente um único endereço — https://mcp.qretro.com — e ele o levará ao QRetro para você entrar. Você verá quem está solicitando: o nome do aplicativo, o endereço para o qual será redirecionado e as permissões solicitadas. Verifique o endereço de retorno, aprove e pronto — o cliente mantém o acesso emitido e o renova automaticamente.

Claude (web e desktop): Configurações → Conectores → Adicionar conector personalizado, cole o endereço.

Claude Code:

claude mcp add --transport http qretro https://mcp.qretro.com

Em seguida, execute /mcp em uma sessão e entre no QRetro — o Claude Code abre o navegador para você e armazena o resultado.

Cursor, VS Code e outros clientes: adicione o servidor por URL nas configurações de MCP do cliente, sem nenhum campo de token. Na primeira solicitação, o cliente abrirá a página de login do QRetro por conta própria.

Conectar com um token de API

Um token é para casos em que ninguém pode pressionar "Autorizar" em um navegador, ou quando o acesso precisa ser mais restrito do que um login oferece:

• Automações sem humano: jobs de CI, scripts cron, execuções de claude -p e do Agent SDK — um fluxo de login exige uma sessão interativa.
• Apenas uma equipe: uma conexão com login sempre cobre todas as equipes das quais você participa; um token pode ser vinculado a uma única equipe.
• Excluir mensagens: mcp:delete só está disponível em tokens.
• Clientes que aceitam apenas um cabeçalho fixo Authorization.

1. Criar um token de API

Acesse Configurações → Chaves de API, escolha as permissões e, se necessário, uma única equipe. Copie o token — ele é exibido apenas uma vez.

2. Passá-lo ao cliente

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "qretro": {
      "url": "https://mcp.qretro.com",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

Claude Code:

claude mcp add --transport http qretro https://mcp.qretro.com --header "Authorization: Bearer YOUR_TOKEN"

Comece a fazer perguntas

Depois de conectado, você pode consultar o sistema com perguntas como:

• "Mostre-me as retrospectivas da equipe Backend"
• "Quais ações foram acordadas no último sprint?"
• "Como a saúde da nossa equipe mudou nos últimos 3 meses?"
• "Pesquise em todas as retros menções a problemas de deploy"

---

Usando esta documentação em clientes MCP

Toda página de documentação tem um bloco de ações no canto superior direito:

• Copiar página – copia a página inteira em formato Markdown. Útil quando você quer "anexar" esta documentação a uma sessão no Claude, Cursor ou ChatGPT.
• Copiar link Markdown – copia um link direto para a versão Markdown da página (por exemplo, https://qretro.com/raw/en/docs/6.mcp.md) que você pode passar para um assistente com um pedido como "Leia esta documentação de MCP e use-a como referência".
• Abrir no ChatGPT / Abrir no Claude – abre o assistente selecionado com uma consulta pré-preenchida como Read https://qretro.com/raw/en/docs/6.mcp.md so I can ask questions about it..

Texto recomendado para usar esta documentação dentro de um cliente MCP (Claude Desktop, Cursor, etc.):

Read the documentation for the QRetro MCP server here:
https://qretro.com/raw/en/docs/6.mcp.md
Use it as the source of truth about available tools and their parameters when working with the QRetro server.

Ferramentas disponíveis

Todas as ferramentas seguem a convenção de nomenclatura domain.scope.action. O QRetro tem dois domínios: retro para retrospectivas e poker para planning poker.

Ferramenta	Descrição
retro.teams.list	Obtenha todas as suas equipes com o número de quadros em cada uma (concluídos e não concluídos)
retro.team.members.list	Quem está na equipe, com a permissão que cada um possui — a fonte dos IDs de usuário para atribuir trabalho
retro.boards.list	Liste as retrospectivas de uma equipe, das mais recentes para as mais antigas — filtre por período com since/until ou finished_only
retro.actions.list	Itens de ação abertos em todas as retrospectivas de uma vez, com equipe, quadro, responsável e flag de atraso
retro.board.messages.list	Obtenha todas as mensagens dos participantes (cartões) organizadas por colunas de template, com sentimento, categoria e votos
retro.board.summary.get	Obtenha o resumo analítico e os participantes
retro.board.actions.list	Obtenha itens de ação com status, prioridade e responsável
retro.board.insights.list	Recupere clusters semânticos e ações sugeridas pelo sistema
retro.board.health.get	Verificação de saúde: pontuação por categoria em uma escala de 0 a 10, alinhamento, participação e a tendência ao longo de retrospectivas anteriores
retro.board.roti.get	Métricas de ROTI com distribuição e tendência histórica
retro.boards.search	Pesquisa por palavras-chave em resumos, itens de ação e cartões de participantes

As ferramentas MCP usam os padrões de nomenclatura retro.* e poker.*, por exemplo retro.teams.list e poker.games.list. Sempre use esses nomes em clientes MCP.

Planning poker

Ferramenta	Descrição
poker.sources.list	Quais rastreadores de issues uma equipe conectou e o que cada um pode fazer: busca, iterações, gravação de estimativas de volta
poker.iterations.list	Sprints de um rastreador conectado, ativos e futuros — filtre por nome com query
poker.games.list	Os jogos de poker de uma equipe, dos mais recentes para os mais antigos, com contagens de tarefas e quantas já possuem estimativa
poker.game.get	Um jogo: escala, progresso, a tarefa na mesa e o link pelo qual os participantes entram
poker.game.tasks.list	Tarefas com estimativa, votos individuais, chave do rastreador e needs_sync

Ferramentas de escrita (exigem escopo mcp:write)

Ferramenta	Descrição
retro.actions.create	Crie um novo item de ação em um quadro
retro.actions.update	Atualize texto, prioridade, data de vencimento ou responsável
retro.actions.complete	Marque um item de ação como concluído
retro.board.suggested_actions.promote	Transforme uma sugestão criada pelo quadro em um acordo, mantendo o texto e o tema de origem
retro.board.suggested_actions.reject	Dispense uma sugestão — nada é adicionado ao quadro
retro.board.messages.update	Edite o texto de uma mensagem existente criada pelo usuário atual
poker.games.create	Abra um jogo de poker para uma equipe com uma escala pronta ou personalizada
poker.game.tasks.add	Adicione tarefas manualmente, para trabalho que vive fora de um rastreador
poker.game.tasks.import	Importe um sprint inteiro, ou resultados de busca, de um rastreador conectado
poker.game.task.select	Coloque uma tarefa na mesa para todos que estão vendo o jogo
poker.game.task.reveal	Revele as cartas e calcule a estimativa a partir dos votos dados
poker.game.task.sync	Grave a estimativa acordada de volta no Jira ou no Linear

As sugestões que o sistema monta após uma retrospectiva começam como pendentes: retro.board.insights.list as mostra, promote transforma uma em acordo no quadro sem redigitá-la, reject a dispensa. Ambas são limitadas às pessoas que podem alterar o quadro, exatamente como na interface, e uma sugestão só pode ser tratada uma vez.

Duas coisas que as ferramentas de poker deliberadamente não podem fazer: definir uma estimativa diretamente (ela só vem de votos revelados) e votar em seu nome. Alterar um jogo — importar tarefas, revelar cartas, sincronizar estimativas — é limitado ao dono da equipe, exatamente como na interface.

Ferramentas de exclusão (exigem escopo mcp:delete)

Ferramenta	Descrição
retro.board.messages.delete_own	Exclua uma mensagem de autoria do usuário atual em quadros aos quais ele tem acesso.

---

Prompts

O QRetro também fornece prompts integrados que guiam seu cliente por uma análise estruturada. Clientes que suportam prompts MCP os reconhecem como comandos prontos, então não há nada para instalar nem para redigir você mesmo. No Claude Code, pressione / e eles aparecem na lista ao lado dos comandos integrados como /mcp__qretro__analyze-retro e /mcp__qretro__team-health — o prefixo é construído a partir do nome que você deu ao servidor ao adicioná-lo.

• analyze-retro — análise aprofundada de uma única retrospectiva: resumo, clusters, acordos, saúde e ROTI em uma única passada, terminando com temas-chave, riscos e o que mudar na próxima vez. Recebe board_id.
• team-health — tendências de saúde nas últimas retrospectivas da equipe: para onde as pontuações e o ROTI estão indo, quantos acordos realmente são fechados, o que continua se repetindo. Recebe team_id.

---

Permissões e escopos

O acesso é sempre limitado por duas coisas ao mesmo tempo: as permissões concedidas ao cliente e sua própria participação nas equipes. Um cliente nunca pode alcançar uma equipe da qual você não participa.

Permissão	O que permite	Entrando com login	Token de API
mcp:read	Ler retrospectivas, mensagens, itens de ação, métricas, jogos de poker	sim	sim
mcp:write	Criar e atualizar itens de ação, mensagens de quadro e jogos de poker	sim	sim
mcp:delete	Excluir suas próprias mensagens de quadro	não	sim

Ferramentas para as quais um cliente não tem permissão não são oferecidas a ele — sem mcp:write ele nem verá retro.actions.create.

As permissões correspondem exatamente à interface: um cliente só pode fazer o que você mesmo poderia fazer no mesmo quadro. Editar um acordo é limitado ao autor e ao dono do quadro; fechar um também está disponível para o responsável; e cartões ocultos por escrita privada durante uma retro em andamento permanecem invisíveis — inclusive na busca.

Ao entrar com login

Não há nada para digitar: o aplicativo solicita as permissões de que precisa, e você as vê na tela de aprovação antes de concordar. Excluir mensagens não está disponível dessa forma — conceda com um token de API se um cliente realmente precisar.

Ao criar um token de API

Você marca as permissões você mesmo em Configurações → Chaves de API. A leitura está sempre incluída; escrita e exclusão são opcionais. Lá você também pode vincular o token a uma única equipe — útil quando um cliente deve ver apenas os dados de uma equipe.

Revogando acesso

• Aplicativos nos quais você entrou — Configurações → Chaves de API, bloco "Aplicativos conectados". Revogar corta o acesso do aplicativo imediatamente: ele perde tanto o acesso atual quanto a capacidade de renová-lo, e precisa pedir novamente.
• Tokens de API — mesma página, lista de tokens. Excluir um token interrompe qualquer cliente que o use.

---

Diretrizes adicionais para clientes assistentes

• Fonte de verdade para permissões: ao trabalhar com itens de ação, trate os flags can_edit e can_complete nos objetos ActionItem (e nas respostas da API) como a única fonte de verdade. Não invente lógica de permissão personalizada em prompts.
• Contexto de equipe: a maioria das ferramentas assume implicitamente um contexto de equipe única (Team). Uma conexão com login sempre cobre todas as equipes das quais você participa, então comece com retro.teams.list e passe team_id explicitamente; ferramentas que precisam de uma equipe nomearão as disponíveis se você omitir.
• Cadeias de chamadas: antes de atualizar ou excluir entidades, sempre busque listas primeiro (retro.boards.list, retro.board.actions.list, retro.board.messages.list) para obter IDs atualizados. Para colocar um nome em um acordo, pegue o ID do usuário de retro.team.members.list — assign_to aceita esse ID ou me.

---

Receitas de uso

Receita A: Análise de Saúde da Equipe

Quando um usuário pedir para "analisar a saúde da equipe", siga esta sequência:

1. Chame retro.teams.list e, em seguida, retro.boards.list com o team_id escolhido (pode ser omitido apenas quando houver um único time disponível).
2. Chame retro.board.health.get para o quadro mais recente — o trend dele já contém a pontuação das retrospectivas anteriores, então não é necessário percorrê-las uma a uma. Adicione retro.board.roti.get se você também quiser o valor percebido das reuniões.
3. Se health_check retornar null, não relate um erro. Em vez disso, responda: “As pesquisas de saúde ainda não foram executadas para este quadro” e continue a análise com base nos dados disponíveis (cartões, resumo, itens de ação).

Receita B: O que combinamos e nunca concluímos

1. Chame retro.actions.list — uma única chamada cobre todos os times, e os itens atrasados vêm primeiro.
2. Reduza o escopo quando necessário: status: "all" para ver também os concluídos, assignee para uma pessoa específica, since para um período, team_id para um único time.
3. Recorra a retro.board.actions.list apenas quando o usuário perguntar sobre uma retrospectiva específica.

Receita C: Configurar planning poker para uma sprint

Quando um usuário disser algo como “configure planning poker para NEXT AFT 50”:

1. Chame poker.sources.list para ver o que o time conectou. Uma lista vazia não é um beco sem saída — pule para o passo 3 e adicione tarefas com poker.game.tasks.add.
2. Chame poker.iterations.list com query: "AFT 50" e use o ref da sprint correspondente. Rastreadores sem suporte a sprint retornam uma lista vazia — use um query de texto na próxima etapa.
3. Chame poker.games.create com o nome da sprint e, em seguida, poker.game.tasks.import com esse ref.
4. Entregue o url da resposta ao time — é lá que as pessoas votam.
5. Quando os votos chegarem: poker.game.task.select, poker.game.task.reveal e poker.game.task.sync para cada tarefa cujo needs_sync seja verdadeiro.

---

Notas sobre dados e ferramentas

Esclarecimentos para ferramentas selecionadas

Ferramenta	Descrição correta
retro.boards.list	Retorna a lista de quadros concluídos de um time. team_id é opcional apenas quando houver um único time disponível; caso contrário, a ferramenta responde com a lista de times para escolher.
retro.actions.update	Atualiza o text, priority, due ou assign_to de um item de ação existente. Requer action_item_id; as verificações finais de permissão são aplicadas no backend por meio de políticas e do contexto do token.