Workflows

Open Source — GitScrum MCP Server is open source under the MIT license. Available on npm and GitHub. Model Context Protocol server for GitScrum — Claude, GitHub Copilot, Cursor, and any MCP-compatible client full operational access to your project management stack.

The workflow tool provides 2 actions for inspecting your project's Kanban workflow configuration — the column structure that defines how tasks move from "to do" through "in progress" to "done." While workflow columns are configured in the GitScrum web application, the MCP Server gives your AI assistant read access to the complete workflow structure, which is essential for creating tasks in the right column, moving tasks between stages, and understanding your team's process.

Workflows in GitScrum define the visual and logical stages of your Kanban board. Each column has a unique id (the workflow_id), a title, a position, and a color. The MCP Server exposes this metadata so your AI assistant can reference columns by name and resolve them to the correct numeric IDs that the task tool requires.

Actions Overview

Listing Workflow Columns

The list action returns all Kanban columns configured for a specific project, in their display order. Each column in the response includes its id (used as workflow_id in task operations), uuid, title, position, and color. This is the definitive source of truth for your project's workflow structure.

Your AI assistant typically calls this action as part of its context-gathering phase — before creating tasks or moving them between columns, it needs to know what columns exist and what their IDs are.

Required Parameters

Response Structure

Each workflow column in the response includes:

Example Prompts

You:  "Show all workflow columns in the Backend project"
AI:   Calls workflow action=list → returns columns with IDs, titles, and positions

You:  "What Kanban columns are available?"
AI:   Calls workflow action=list → presents the board structure: Backlog → To Do →
      In Progress → Code Review → QA → Done

You:  "List the workflow stages for the Frontend project"
AI:   Calls workflow action=list → returns the column configuration

You:  "How is our Kanban board structured?"
AI:   Calls workflow action=list → describes the column flow from left to right

Getting Column Details

The get action returns the complete details of a specific workflow column, including all its metadata and configuration properties. This is useful when you need detailed information about a particular stage in your workflow.

Required Parameters

Example Prompts

You:  "Show me the details of the 'In Progress' column"
AI:   Finds the column via list → calls workflow action=get → returns full details

You:  "What's the configuration for the Code Review column?"
AI:   Calls workflow action=get with the column's UUID → returns complete metadata

How Workflows Connect to Tasks

The workflow column IDs are the foundation for task placement on the Kanban board. Understanding this connection is essential for effective MCP-driven project management.

Creating tasks in a specific column

When creating a task, you can place it in a specific column using either:

• column (string): The column name (e.g. "In Progress"). The MCP server resolves this to the correct workflow_id automatically.
• workflow_id (number): The numeric column ID from the workflow list. Use this when you already have the ID from a previous workflow action=list call.

The column parameter is recommended for most use cases because it's more natural in conversation. The MCP server handles the name-to-ID resolution behind the scenes.

You:  "Create a task 'Fix login validation' in the In Progress column"
AI:   Calls task action=create with column="In Progress"
      → MCP server resolves to workflow_id automatically

You:  "Add a task to the Code Review column"
AI:   Calls task action=create with column="Code Review"

Moving tasks between columns

When updating a task's column, you can use the same column parameter:

You:  "Move task GS-123 to Done"
AI:   Calls task action=update with column="Done"
      → MCP server resolves the column name to workflow_id

You:  "Move the login fix to Code Review"
AI:   Calls task action=update with column="Code Review"

Transferring tasks across projects

When moving a task to a different project using the task action=move, you need the newworkflowid from the target project. Different projects may have different workflow configurations, so the AI assistant needs to list the target project's workflows first:

You:  "Move task GS-123 to the Frontend project's Backlog"
AI:   1. Calls workflow action=list for the Frontend project
      2. Finds the "Backlog" column ID
      3. Calls task action=move with new_project_slug and new_workflow_id

Smart Column Resolution

The MCP Server includes built-in column name resolution — a feature that saves your AI assistant an extra API call in many scenarios. When you pass a column parameter by name to the task tool's create or update actions, the server:

1. Fetches the project's workflow configuration
2. Matches the column name (case-insensitive)
3. Resolves it to the numeric workflow_id
4. Executes the task operation with the correct ID

If the column name doesn't match any existing column, the server returns an error message that includes the list of available column names. This allows the AI assistant to suggest the correct column name to you:

You:  "Move the task to Review"
AI:   Tries column="Review" → server returns "Column not found. Available columns:
      Backlog, To Do, In Progress, Code Review, QA, Done"
AI:   "I don't see a 'Review' column. Did you mean 'Code Review'?"

Column-Based Task Management

Workflow columns enable powerful task queries and operations. By combining workflow knowledge with the task filter action, your AI assistant can answer board-level questions:

Checking column contents

You:  "What tasks are in the In Progress column?"
AI:   Calls task action=filter with workflow="In Progress"
      → returns all tasks currently in that column

You:  "How many tasks are in Code Review?"
AI:   Calls task action=filter with workflow="Code Review"
      → counts and reports the results

You:  "Show me the Backlog"
AI:   Calls task action=filter with workflow="Backlog"
      → returns all tasks in the Backlog column

Identifying bottlenecks

You:  "Which column has the most tasks?"
AI:   Calls workflow action=list → for each column, calls task action=filter
      → identifies the column with the highest task count

You:  "Are there any bottlenecks in our workflow?"
AI:   Analyzes task counts per column → flags columns with disproportionately
      high task counts relative to others

You:  "How long have tasks been sitting in Code Review?"
AI:   Calls task action=filter with workflow="Code Review"
      → analyzes task creation dates and time in column

Daily standup queries

You:  "Give me a standup summary: what moved yesterday, what's in progress,
       and what's blocked?"
AI:   Filters tasks by column and recent activity → generates a structured
      standup report covering Done (yesterday), In Progress (today), and blocked items

Typical Workflow Configurations

While every team configures their board differently, these are common workflow patterns you'll encounter:

Simple workflow

Backlog → In Progress → Done

Development workflow

Backlog → To Do → In Progress → Code Review → QA → Done

Agency workflow

Brief → Design → Development → Review → Client Approval → Done

Support workflow

New → Triaged → In Progress → Resolved → Closed

The MCP Server works with any configuration — your AI assistant adapts to whatever columns your project uses by reading the workflow structure at the start of the conversation.

Context Auto-Resolution

The workflow tool supports automatic context resolution. If the AI assistant already knows your workspace and project from a previous call in the conversation, it carries that context forward. Additionally, when the task tool's smart column resolution is used, the workflow lookup happens automatically — you don't need to explicitly call workflow action=list before every task operation.

Next Steps

• Tasks: Create and move tasks across workflow columns.
• Task Types: Configure task types for categorizing work within columns.
• Sprints: Track how tasks flow through columns during a sprint.
• Projects: Manage the project settings that include workflow configuration.
• Quick Start: Set up the MCP server if you haven't already.