QRetro

Connect Claude, Cursor y otros clientes analíticos a tus retrospectivas mediante el Protocolo de Contexto de Modelos

Qué es MCP

El Protocolo de Contexto de Modelos (MCP) es un estándar abierto que permite a sistemas externos y algoritmos acceder a datos. QRetro proporciona un servidor MCP para que puedas consultar los datos de tus retrospectivas desde Claude Desktop, Cursor, VS Code y otros clientes compatibles directamente.

Dos formas de conectarse

	Iniciando sesión	Token de API
Lo que le das al cliente	Solo la dirección https://mcp.qretro.com	Una cadena de token que creas tú mismo
A quién le conviene	Claude, Claude Code, Cursor, VS Code — cualquier cosa con un navegador a mano	Automatizaciones, CI, clientes con un encabezado fijo
Alcance de acceso	Todos los equipos a los que perteneces	Opcionalmente un solo equipo
Eliminar mensajes	No disponible	Disponible con mcp:delete
Revocación	Configuración → Claves de API → Aplicaciones conectadas	Configuración → Claves de API

Conectar iniciando sesión

Dale al cliente una sola dirección — https://mcp.qretro.com — y te llevará a QRetro para iniciar sesión. Verás quién está preguntando: el nombre de la aplicación, la dirección a la que serás devuelto y los permisos solicitados. Verifica la dirección de retorno, aprueba y listo — el cliente conserva el acceso emitido y lo renueva por sí solo.

Claude (web y escritorio): Configuración → Conectores → Añadir conector personalizado, pega la dirección.

Claude Code:

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

Luego ejecuta /mcp en una sesión e inicia sesión en QRetro — Claude Code abre el navegador por ti y almacena el resultado.

Cursor, VS Code y otros clientes: añade el servidor por URL en la configuración MCP del cliente, sin ningún campo de token. En la primera solicitud, el cliente abrirá la página de inicio de sesión de QRetro por sí mismo.

Conectar con un token de API

Un token es para casos donde nadie puede pulsar "Autorizar" en un navegador, o donde el acceso necesita ser más restringido que lo que ofrece un inicio de sesión:

• Automatizaciones sin humano: trabajos de CI, scripts cron, ejecuciones de claude -p y Agent SDK — un flujo de inicio de sesión necesita una sesión interactiva.
• Solo un equipo: una conexión con inicio de sesión siempre cubre todos los equipos a los que perteneces; un token puede estar vinculado a un solo equipo.
• Eliminar mensajes: mcp:delete solo está disponible en tokens.
• Clientes que solo aceptan un encabezado fijo Authorization.

1. Crear un token de API

Ve a Configuración → Claves de API, elige los permisos y, si es necesario, un solo equipo. Copia el token — solo se muestra una vez.

2. Pasarlo al 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"

Empieza a hacer preguntas

Una vez conectado, puedes consultar el sistema con preguntas como:

• "Muéstrame las retrospectivas del equipo Backend"
• "¿Qué acciones se acordaron en el último sprint?"
• "¿Cómo ha cambiado la salud de nuestro equipo en los últimos 3 meses?"
• "Busca en todas las retros menciones a problemas de despliegue"

---

Uso de esta documentación en clientes MCP

Cada página de documentación tiene un bloque de acciones en la esquina superior derecha:

• Copiar página – copia la página completa en formato Markdown. Útil cuando quieres "adjuntar" esta documentación a una sesión en Claude, Cursor o ChatGPT.
• Copiar enlace Markdown – copia un enlace directo a la versión Markdown de la página (por ejemplo, https://qretro.com/raw/en/docs/6.mcp.md) que puedes pasar a un asistente con una solicitud como "Lee esta documentación MCP y úsala como referencia".
• Abrir en ChatGPT / Abrir en Claude – abre el asistente seleccionado con una consulta prellenada como Read https://qretro.com/raw/en/docs/6.mcp.md so I can ask questions about it..

Texto recomendado para usar esta documentación dentro de un 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.

Herramientas disponibles

Todas las herramientas siguen la convención de nomenclatura domain.scope.action. QRetro tiene dos dominios: retro para retrospectivas y poker para planning poker.

Herramienta	Descripción
retro.teams.list	Obtén todos tus equipos con el número de tableros en cada uno (terminados y sin terminar)
retro.team.members.list	Quién está en el equipo, con el permiso que tiene cada uno — la fuente de IDs de usuario para asignar trabajo
retro.boards.list	Lista las retrospectivas de un equipo, de más reciente a más antigua — filtra por período con since/until o finished_only
retro.actions.list	Elementos de acción abiertos en todas las retrospectivas a la vez, con equipo, tablero, asignado y marca de vencido
retro.board.messages.list	Obtén todos los mensajes de participantes (tarjetas) organizados por columnas de plantilla, con sentimiento, categoría y votos
retro.board.summary.get	Obtén el resumen analítico y los participantes
retro.board.actions.list	Obtén elementos de acción con estado, prioridad y asignado
retro.board.insights.list	Recupera clústeres semánticos y acciones sugeridas por el sistema
retro.board.health.get	Verificación de salud: puntuación por categoría en una escala de 0 a 10, alineación, participación y la tendencia en retrospectivas anteriores
retro.board.roti.get	Métricas ROTI con distribución y tendencia histórica
retro.boards.search	Búsqueda por palabras clave en resúmenes, elementos de acción y tarjetas de participantes

Las herramientas MCP usan los patrones de nomenclatura retro.* y poker.*, por ejemplo retro.teams.list y poker.games.list. Usa siempre estos nombres en los clientes MCP.

Planning poker

Herramienta	Descripción
poker.sources.list	Qué rastreadores de incidencias tiene conectados un equipo y qué puede hacer cada uno: búsqueda, iteraciones, escribir estimaciones de vuelta
poker.iterations.list	Sprints de un rastreador conectado, activos y próximos — filtra por nombre con query
poker.games.list	Los juegos de poker de un equipo, de más reciente a más antiguo, con recuentos de tareas y cuántas ya tienen una estimación
poker.game.get	Un juego: escala, progreso, la tarea sobre la mesa y el enlace al que se unen los participantes
poker.game.tasks.list	Tareas con estimación, votos individuales, clave del rastreador y needs_sync

Herramientas de escritura (requieren alcance mcp:write)

Herramienta	Descripción
retro.actions.create	Crea un nuevo elemento de acción en un tablero
retro.actions.update	Actualiza texto, prioridad, fecha de vencimiento o asignado
retro.actions.complete	Marca un elemento de acción como completado
retro.board.suggested_actions.promote	Convierte una sugerencia que generó el tablero en un acuerdo, conservando su redacción y el tema del que proviene
retro.board.suggested_actions.reject	Descarta una sugerencia — no se añade nada al tablero
retro.board.messages.update	Edita el texto de un mensaje existente creado por el usuario actual
poker.games.create	Abre un juego de poker para un equipo con una escala prefabricada o personalizada
poker.game.tasks.add	Añade tareas manualmente, para trabajo que vive fuera de un rastreador
poker.game.tasks.import	Trae un sprint completo, o resultados de búsqueda, desde un rastreador conectado
poker.game.task.select	Pon una tarea sobre la mesa para todos los que miran el juego
poker.game.task.reveal	Revela las cartas y calcula la estimación a partir de los votos emitidos
poker.game.task.sync	Escribe la estimación acordada de vuelta en Jira o Linear

Las sugerencias que el sistema elabora después de una retrospectiva comienzan como pendientes: retro.board.insights.list las muestra, promote convierte una en un acuerdo en el tablero sin volver a escribirla, reject la descarta. Ambas están limitadas a las personas que pueden modificar el tablero, exactamente como en la interfaz, y una sugerencia solo puede gestionarse una vez.

Dos cosas que las herramientas de poker deliberadamente no pueden hacer: establecer una estimación directamente (solo proviene de votos revelados) y votar en tu nombre. Cambiar un juego — importar tareas, revelar cartas, sincronizar estimaciones — está limitado al propietario del equipo, exactamente como en la interfaz.

Herramientas de eliminación (requieren alcance mcp:delete)

Herramienta	Descripción
retro.board.messages.delete_own	Elimina un mensaje creado por el usuario actual en tableros a los que tiene acceso.

---

Prompts

QRetro también proporciona prompts integrados que guían a tu cliente a través de un análisis estructurado. Los clientes que admiten prompts MCP los toman como comandos listos para usar, así que no hay nada que instalar ni que redactar tú mismo. En Claude Code, pulsa / y aparecerán en la lista junto a los comandos integrados como /mcp__qretro__analyze-retro y /mcp__qretro__team-health — el prefijo se construye a partir del nombre que le diste al servidor al añadirlo.

• analyze-retro — análisis profundo de una sola retrospectiva: resumen, clústeres, acuerdos, salud y ROTI en una sola pasada, terminando con temas clave, riesgos y qué cambiar la próxima vez. Toma board_id.
• team-health — tendencias de salud en las últimas retrospectivas del equipo: hacia dónde se dirigen las puntuaciones y el ROTI, cuántos acuerdos se cierran realmente, qué se repite. Toma team_id.

---

Permisos y alcances

El acceso siempre está limitado por dos cosas a la vez: los permisos otorgados al cliente y tu propia membresía en equipos. Un cliente nunca puede alcanzar un equipo al que no perteneces.

Permiso	Qué permite	Iniciando sesión	Token de API
mcp:read	Leer retrospectivas, mensajes, elementos de acción, métricas, juegos de poker	sí	sí
mcp:write	Crear y actualizar elementos de acción, mensajes de tablero y juegos de poker	sí	sí
mcp:delete	Eliminar tus propios mensajes de tablero	no	sí

Las herramientas para las que un cliente no tiene permiso no se le ofrecen en absoluto — sin mcp:write ni siquiera verá retro.actions.create.

Los permisos coinciden exactamente con la interfaz: un cliente solo puede hacer lo que tú podrías hacer tú mismo en el mismo tablero. Editar un acuerdo está limitado a su autor y al propietario del tablero, cerrarlo también está disponible para el asignado, y las tarjetas ocultas por escritura privada durante una retro en curso permanecen invisibles — incluso en la búsqueda.

Al iniciar sesión

No hay nada que escribir: la aplicación solicita los permisos que necesita y los ves en la pantalla de aprobación antes de aceptar. Eliminar mensajes no está disponible de esta manera — concédelo con un token de API si un cliente realmente lo necesita.

Al crear un token de API

Tú marcas los permisos tú mismo en Configuración → Claves de API. La lectura siempre está incluida; escribir y eliminar son opcionales. Allí también puedes vincular el token a un solo equipo — útil cuando un cliente solo debe ver los datos de un equipo.

Revocar acceso

• Aplicaciones en las que iniciaste sesión — Configuración → Claves de API, el bloque "Aplicaciones conectadas". Revocar corta la aplicación de inmediato: pierde tanto su acceso actual como la capacidad de renovarlo, y tiene que pedírtelo de nuevo.
• Tokens de API — misma página, la lista de tokens. Eliminar un token detiene a cualquier cliente que lo use.

---

Directrices adicionales para clientes asistente

• Fuente de verdad para permisos: al trabajar con elementos de acción, trata los indicadores can_edit y can_complete en los objetos ActionItem (y en las respuestas de API) como la única fuente de verdad. No inventes lógica de permisos personalizada en los prompts.
• Contexto de equipo: la mayoría de las herramientas asumen implícitamente un contexto de un solo equipo (Team). Una conexión con inicio de sesión siempre cubre todos los equipos a los que perteneces, así que empieza con retro.teams.list y pasa team_id explícitamente; las herramientas que necesitan un equipo nombrarán los disponibles si lo omites.
• Cadenas de llamadas: antes de actualizar o eliminar entidades, obtén siempre primero las listas (retro.boards.list, retro.board.actions.list, retro.board.messages.list) para conseguir IDs frescos. Para poner un nombre a un acuerdo, toma el ID de usuario de retro.team.members.list — assign_to acepta ese ID o me.

---

Recetas de uso

Receta A: Análisis de salud del equipo

Cuando un usuario pida "analizar la salud del equipo", sigue esta secuencia:

1. Llama a retro.teams.list, luego a retro.boards.list con el team_id elegido (puede omitirse solo cuando hay un único equipo disponible).
2. Llama a retro.board.health.get para el tablero más reciente: su trend ya contiene la puntuación de las retrospectivas anteriores, por lo que no es necesario revisarlas una por una. Añade retro.board.roti.get si también deseas el valor percibido de las reuniones.
3. Si health_check devuelve null, no informes un error. En su lugar, responde: “Las encuestas de salud aún no se han ejecutado para este tablero” y continúa el análisis basándote en los datos disponibles (tarjetas, resumen, elementos de acción).

Receta B: Lo que acordamos y nunca terminamos

1. Llama a retro.actions.list: una sola llamada cubre todos los equipos, y los elementos vencidos aparecen primero.
2. Reduce el alcance cuando sea necesario: status: "all" para ver también los completados, assignee para una persona en particular, since para un período, team_id para un solo equipo.
3. Recurre a retro.board.actions.list solo cuando el usuario pregunte por una retrospectiva específica.

Receta C: Configurar planning poker para un sprint

Cuando un usuario diga algo como “configura planning poker para NEXT AFT 50”:

1. Llama a poker.sources.list para ver qué tiene conectado el equipo. Una lista vacía no es un callejón sin salida: salta al paso 3 y añade tareas con poker.game.tasks.add.
2. Llama a poker.iterations.list con query: "AFT 50" y toma el ref del sprint que coincida. Los rastreadores sin soporte de sprints devuelven una lista vacía: usa un query de texto en el siguiente paso en su lugar.
3. Llama a poker.games.create con el nombre del sprint, luego a poker.game.tasks.import con ese ref.
4. Entrega el url de la respuesta al equipo: ahí es donde la gente vota.
5. Una vez que lleguen los votos: poker.game.task.select, poker.game.task.reveal y poker.game.task.sync para cada tarea cuyo needs_sync sea verdadero.

---

Notas sobre datos y herramientas

Aclaraciones para herramientas seleccionadas

Herramienta	Descripción correcta
retro.boards.list	Devuelve la lista de tableros completados para un equipo. team_id es opcional solo cuando hay un único equipo disponible; de lo contrario, la herramienta responde con la lista de equipos para elegir.
retro.actions.update	Actualiza el text, priority, due o assign_to de un elemento de acción existente. Requiere action_item_id; las comprobaciones finales de permisos se aplican en el backend mediante políticas y el contexto del token.