Integration via MCP

What is MCP

Model Context Protocol (MCP) is an open standard that lets external systems and algorithms access data. QRetro provides an MCP server so you can query your retrospective data from Claude Desktop, Cursor, VS Code, and other compatible clients directly.

Quick Start

1. Create an API Token

Go to Settings → API Keys and create a new token. Copy the token — it is shown only once.

2. Configure Your Client

Add the QRetro MCP server to your client configuration.

Claude Desktop (claude_desktop_config.json):

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

3. Start Asking Questions

Once connected, you can query the system with questions like:

• "Show me the retrospectives for the Backend team"
• "What actions were agreed on in the last sprint?"
• "How has our team health changed over the last 3 months?"
• "Search all retros for mentions of deployment problems"

Using this documentation in MCP clients

Every documentation page has an action block in the top-right corner:

• Copy page – copies the full page in Markdown format. Useful when you want to “attach” this documentation to a session in Claude, Cursor, or ChatGPT.
• Copy Markdown link – copies a direct link to the Markdown version of the page (for example, https://qretro.com/raw/en/docs/6.mcp.md) that you can pass to an assistant with a request like “Read this MCP documentation and use it as a reference”.
• Open in ChatGPT / Open in Claude – open the selected assistant with a pre-filled query like Read https://qretro.com/raw/en/docs/6.mcp.md so I can ask questions about it..

Recommended text for using this documentation inside an MCP client (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.

Available Tools

All tools follow the domain.scope.action naming convention. For QRetro the domain is retro.

MCP tools use the retro.* naming pattern, for example retro.teams.list and retro.boards.draft.get. Always use these names in MCP clients.

Write Tools (require mcp:write scope)

Delete Tools (require mcp:delete scope)

Prompts

QRetro also provides built-in prompts that guide your client through structured analysis:

• Analyze Retro — deep-dive into a single retrospective: key themes, action quality, team dynamics
• Team Health — analyze health trends across multiple retrospectives, spot systemic risks and burnout signals

Security

• Tokens have mcp:read scope by default. For write operations, use tokens with mcp:write scope.
• Each token is scoped to the user who created it.
• You can revoke tokens at any time in Settings → API Keys.

Delete permissions (mcp:delete)

The mcp:delete scope gives an MCP client limited delete access:

• With mcp:delete, the client can call the retro.board.messages.delete_own tool to delete only messages authored by the token owner on boards they have access to.

Additional guidelines for assistant clients

• Source of truth for permissions: when working with action items, treat the can_edit and can_complete flags on ActionItem objects (and API responses) as the single source of truth. Do not invent custom permission logic in prompts.
• Team context: most tools implicitly assume a single team (Team) context. For stable MCP usage it is recommended to use API tokens scoped to a single team (Team‑scoped token).
• Call chains: before updating or deleting entities, always fetch lists first (retro.boards.list, retro.board.actions.list, retro.board.messages.list) to obtain fresh IDs.

Usage recipes

Recipe A: Team Health analysis

When a user asks to “analyze the team’s health”, follow this sequence:

1. Call retro.boards.list (ensure the token is scoped to a single team; if you get a “Multiple teams available” error, suggest creating a Team‑scoped token).
2. For the last 3–5 boards, call both retro.board.health.get and retro.board.roti.get.
3. If health_check returns null, do not report an error. Instead answer: “Health surveys were not run for this board yet” and continue the analysis based on available data (cards, summary, action items).

Recipe B: Working with a draft

When saving a user’s ideas or notes:

1. Call retro.boards.draft.get.
2. If the response contains draft: null, tell the user: “This team has no active draft board. Please create one in the web interface (Draft section) so I can save notes there.”
3. If a draft exists, use retro.board.messages.draft.create:
   • you may choose the column automatically (by intent such as positive, negative, idea, etc.) or omit it to let the server determine the best column via IntentAnalyzerService;
   • if there is no suitable draft board, the tool will return Active draft board not found. — in that case also suggest creating a draft in the UI.

Notes on data and tools

Data fields

• Action items on drafts: use the open_action_items field in the retro.boards.draft.get response (the older name team_open_action_items should not be used).

Clarifications for selected tools