Get Board Details via MCP: Columns, States, and Usage

Developer reference for the get_board MCP tool. Learn how to retrieve complete details of a specific board including columns, states, task counts, and workflow configuration. Includes example tool calls, natural language prompts, edge cases, and troubleshooting.

Tool Overview

Purpose

The get_board tool retrieves complete details of a specific board by its ID. Use this tool when you need full context about a board including its columns, states, task distribution, and workflow configuration before analyzing bottlenecks or generating reports.

Read-only operation: This tool only reads data - it never modifies boards.

Input Parameters

The tool requires a board ID to retrieve the board details.

Output Format

The tool returns a complete board object with all available fields:

{
  "id": 789,
  "name": "Sprint Board",
  "project_id": 456,
  "project_name": "Q1 Product Launch",
  "created_at": "2026-01-01T10:00:00Z",
  "updated_at": "2026-03-10T14:30:00Z",
  "columns": [
    {
      "id": 1,
      "name": "To Do",
      "position": 0,
      "task_count": 5
    },
    {
      "id": 2,
      "name": "In Progress",
      "position": 1,
      "task_count": 8
    },
    {
      "id": 3,
      "name": "Review",
      "position": 2,
      "task_count": 2
    },
    {
      "id": 4,
      "name": "Done",
      "position": 3,
      "task_count": 0
    }
  ],
  "states": ["open", "in_progress", "review", "done"],
  "task_count": 15,
  "total_tasks": 15
}

Response Fields

• id: Unique board identifier
• name: Board name
• project_id: ID of the project this board belongs to
• project_name: Name of the project (for convenience)
• created_at: Timestamp when board was created
• updated_at: Timestamp when board was last updated
• columns: Array of column objects with id, name, position, and task_count
• states: Array of state strings that map to task statuses
• task_count: Total number of tasks on this board
• total_tasks: Same as task_count (for consistency)

Column Object Fields

• id: Unique column identifier
• name: Column name (e.g., "To Do", "In Progress")
• position: Column order (0-based index)
• task_count: Number of tasks currently in this column

Example Tool Calls

Example 1: Get Board by ID

Tool Call (JSON):

{
  "tool": "get_board",
  "arguments": {
    "board_id": 789
  }
}

Returns: Complete board object with all fields including columns and states

Natural Language Prompt Examples

Claude Desktop / General AI

User Prompt:

"Show me the structure of the Sprint board"

AI Behavior:

1. AI calls list_boards with search: "Sprint"
2. AI finds board ID (789)
3. AI calls get_board with board_id: 789
4. AI receives complete board object with columns
5. AI formats and presents board structure to user

Analyzing Board Bottlenecks

User Prompt:

"Where are tasks getting stuck on the Sprint board?"

AI Behavior:

1. AI finds board using list_boards
2. AI calls get_board to get column structure and task counts
3. AI analyzes task distribution across columns
4. AI identifies columns with high task counts (bottlenecks)
5. AI presents analysis: "Most tasks (8) are in 'In Progress' column..."

Understanding Workflow

User Prompt:

"What are the workflow states for the Sprint board?"

AI Behavior:

1. AI calls get_board to get board details
2. AI extracts states array from response
3. AI presents workflow: "The Sprint board has these states: open, in_progress, review, done"

Common Use Cases

• Board Bottlenecks - Analyze column task counts to find workflow bottlenecks
• Task Management - Understand board structure before managing tasks
• Project Kickoff - Review board configuration before creating tasks
• Find Board First - Use list_boards to find ID before calling get_board

Edge Cases

Board Not Found (404)

Situation: Board ID doesn't exist or was deleted

Response:

{
  "error": "not_found",
  "message": "Board with ID 789 not found"
}

Handling: Verify the board ID is correct, or check if the board was deleted

Permission Denied (403)

Situation: Board exists but you don't have access

Response:

{
  "error": "forbidden",
  "message": "You don't have permission to access this board"
}

Handling: Check if you're in the correct workspace or if the board is private

Read 403 troubleshooting guide →

Invalid Board ID

Situation: Board ID is not a valid integer

Response:

{
  "error": "validation_error",
  "message": "Invalid board_id format",
  "field": "board_id"
}

Handling: Ensure board_id is a valid integer

Troubleshooting

Invalid Board ID

Symptom: 400 validation error or 404 not found

Causes:

• Board ID is not a number
• Board ID doesn't exist
• Board was deleted

Fix:

• Verify board ID is a valid integer
• Use list_boards to find the correct board ID
• Check if board still exists in Corcava

Access Denied (403)

Symptom: 403 Forbidden error

Causes:

• Board belongs to a different workspace
• Board is private and you're not a member
• API key doesn't have access to the workspace

Fix:

• Verify you're accessing the correct workspace
• Check board permissions in Corcava
• Verify API key has access to the workspace

Read 403 troubleshooting guide →

Best Practices

Using get_board Effectively

• ✅ Always call list_boards first to find board ID if you only know the name
• ✅ Use column task counts to identify bottlenecks in workflow
• ✅ Review states array to understand valid task status transitions
• ✅ Use board details to understand workflow before creating tasks
• ✅ Combine with list_tasks filtered by board_id for detailed analysis

Related Tools

Often used together with:

• list_boards - Find board IDs before calling get_board
• list_tasks - Get tasks on a board using board_id
• list_projects - Find project details for the board's project