MCP Integration Guide

Use Claude, GPT, or any AI assistant to manage planning poker sessions programmatically

What is MCP?

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

Create and manage planning poker sessions
Add user stories programmatically
Set stories for voting
Reveal votes and get consensus
Retrieve session context and history
Organize sessions in folders

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

create_session

CREATE

Create a new planning poker session

Parameters:

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

list_sessions

READ

List all planning poker 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)

MCP API Endpoints

GET /api/scrumpoker/mcp/tools

List all available MCP tools with parameters and descriptions

Example Response:

{
  "success": true,
  "tools": [
    {
      "name": "create_session",
      "description": "Create a new planning poker session",
      "parameters": {
        "name": { "type": "string", "required": true },
        "description": { "type": "string", "required": false }
      }
    }
  ]
}

POST /api/scrumpoker/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 /api/scrumpoker/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 require authentication using Laravel Sanctum tokens. Include your token in the Authorization header:

Authorization: Bearer YOUR_TOKEN_HERE

Note: MCP integration is designed for AI assistants with proper authentication. Each assistant should have its own user account with appropriate permissions.