MCP Integration Guide

Use Claude, GPT, or any AI assistant to manage retrospectives, action items, and connected sprint workflow context programmatically

What is MCP?

Model Context Protocol (MCP) is a standardized way for AI assistants to interact with external tools and services. FreeRetrospectives.com's MCP integration allows AI assistants like Claude or ChatGPT to:

Use Cases

Natural Language Planning

"Create a planning session for Sprint 42 and add these 5 user stories..."

Session History Analysis

"Show me the voting patterns from last month's sessions"

Estimation Insights

"What's the average estimate for authentication stories?"

Automation

"Create sessions from Jira tickets and pre-populate stories"

Available MCP Tools

The MCP surface now covers room management, AI planning tools, vote-history settings, Vote-by deadlines, custom card decks, workspaces, templates, and analytics. Generate a dedicated token from the dashboard and call /mcp/tools, /mcp/execute, and /mcp/context/{session}.

create_session

CREATE

Create a new planning session

Parameters:
  • name - Session name (required)
  • description - Session description (optional)
  • folder_id - Folder to organize in (optional)

list_sessions

READ

List all planning and retrospective sessions

Parameters:
  • folder_id - Filter by folder (optional)
  • status - Filter by status (optional)

get_session

READ

Get details of a specific session

Parameters:
  • session_id - Session UUID or code (required)

add_story

CREATE

Add a new story to a session

Parameters:
  • session_id - Session UUID (required)
  • title - Story title (required)
  • description - Story description (optional)
  • acceptance_criteria - Acceptance criteria (optional)

list_stories

READ

List all stories in a session

Parameters:
  • session_id - Session UUID (required)

set_current_story

UPDATE

Set a story as current for voting

Parameters:
  • story_id - Story UUID (required)

reveal_votes

ACTION

Reveal votes and calculate consensus

Parameters:
  • story_id - Story UUID (required)

get_activity

READ

Get activity log for a session

Parameters:
  • session_id - Session UUID (required)
  • limit - Max activities to return (default: 50)

AI and session-setting tools

NEW

Additional MCP tools are available for AI-assisted planning and session controls:

  • update_session_settings for named voting, Vote-by deadlines, and custom decks
  • summarize_session_ai and analyze_current_story_ai
  • draft_stories_ai and split_current_story_ai
  • improve_current_story_ai and generate_acceptance_criteria_ai

MCP API Endpoints

GET /mcp/tools

List all available MCP tools with parameters and descriptions

Example Response: 
{
  "success": true,
  "tools": [
    {
      "name": "create_session",
      "description": "Create a new planning session",
      "parameters": {
        "name": { "type": "string", "required": true },
        "description": { "type": "string", "required": false }
      }
    }
  ]
}
POST /mcp/execute

Execute an MCP tool

Example Request: 
{
  "tool": "create_session",
  "parameters": {
    "name": "Sprint 42 Planning",
    "description": "Estimate authentication module stories"
  }
}
Example Response: 
{
  "success": true,
  "session": {
    "id": "uuid-here",
    "name": "Sprint 42 Planning",
    "code": "ABC123",
    "status": "active"
  }
}
GET /mcp/context/{session}

Get complete session context for AI understanding

Example Response: 
{
  "success": true,
  "context": {
    "session": { "name": "...", "code": "...", "status": "..." },
    "current_story": { "title": "...", "status": "..." },
    "total_stories": 5,
    "pending_stories": 2,
    "completed_stories": 3,
    "total_participants": 4,
    "recent_activity": [...]
  }
}

Example AI Prompts

"Create a planning session for Sprint 42"

AI will use create_session tool

"Add 3 user stories about authentication to my latest session"

AI will use list_sessions then add_story (3 times)

"What stories are pending in session ABC123?"

AI will use get_session and list_stories

"Start voting on the first pending story"

AI will use list_stories then set_current_story

"Show me the voting history for this session"

AI will use get_activity and analyze patterns

Authentication

All MCP endpoints are served by the Laravel API on https://api.freeretrospectives.com and require authentication using Laravel Sanctum tokens. Include your token in the Authorization header: 

Authorization: Bearer YOUR_TOKEN_HERE

Get Your MCP Token

  1. Log in at https://freeretrospectives.com.
  2. Open the dashboard.
  3. Open Manage Integrations, then use the API/MCP Access panel.
  4. Generate a dedicated MCP token and copy it immediately.

The browser session token also works for first-party flows, but the dashboard-generated MCP token is the supported way to connect external MCP clients.

Token management endpoints:

  • GET /mcp/token
  • POST /mcp/token
  • DELETE /mcp/token

Note: Use GET /mcp/tools for tool discovery. POST /mcp/execute and GET /mcp/context/{session} require a valid bearer token and accept a session UUID or session code where noted.

New integration and analytics tools

MCP clients can now discover usable CSV, GitHub, Linear, Jira, Azure DevOps, Trello, Notion, Slack, and webhook integrations, start guided provider/manual setup, preview issue imports, sync final estimates back to source tools, inspect analytics, generate AI estimation reports, and schedule vote-by deadlines.

list_integrations start_integration_connection import_issues sync_estimates list_sync_logs get_session_analytics generate_ai_estimation_report schedule_vote_deadline create_room_from_template