List Boards via MCP: Finding the Right Workflow Board

Developer reference for the list_boards MCP tool. Learn how to discover and search boards in your workspace, filter by project, and use pagination. Includes example tool calls, natural language prompts, edge cases, and troubleshooting.

Tool Overview

Purpose

The list_boards tool allows you to discover and search boards in your Corcava workspace. Boards represent workflows (like Kanban boards) where tasks move through different states. Use this tool to find boards by name, filter by project, or get an overview of all your workflow boards.

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

Input Parameters

All parameters are optional. If no parameters are provided, returns all boards you have access to (paginated).

Output Format

The tool returns a JSON object with boards and pagination information:

{
  "boards": [
    {
      "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",
      "task_count": 15,
      "column_count": 4
    }
  ],
  "total": 8,
  "limit": 25,
  "offset": 0,
  "has_more": false
}

Response Fields

• boards: Array of board objects (empty array if no matches)
• total: Total number of boards matching the filters (across all pages)
• limit: Maximum number of boards returned in this response
• offset: Number of boards skipped (for pagination)
• has_more: Boolean indicating if more boards are available

Board Object 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
• task_count: Total number of tasks on this board
• column_count: Number of columns/states in the board

Example Tool Calls

Example 1: List All Boards

Tool Call (JSON):

{
  "tool": "list_boards",
  "arguments": {
    "limit": 50
  }
}

Returns: First 50 boards from your workspace

Example 2: Boards in a Project

Tool Call (JSON):

{
  "tool": "list_boards",
  "arguments": {
    "project_id": 456,
    "limit": 25
  }
}

Returns: All boards in project 456

Example 3: Search Boards by Name

Tool Call (JSON):

{
  "tool": "list_boards",
  "arguments": {
    "search": "Sprint",
    "limit": 25
  }
}

Returns: Boards matching "Sprint" in name

Natural Language Prompt Examples

Claude Desktop / General AI

User Prompt:

"Show me all boards in the Q1 project"

AI Behavior:

1. AI calls list_projects to find Q1 project ID
2. AI calls list_boards with project_id filter
3. AI receives list of boards
4. AI formats and presents board list to user

Finding a Specific Board

User Prompt:

"Find the Sprint board"

AI Behavior:

1. AI calls list_boards with search: "Sprint"
2. AI receives matching boards
3. AI shows matching boards or asks for clarification if multiple matches

Selecting Workflow Board

User Prompt:

"What boards are available for the Q1 project?"

AI Behavior:

1. AI finds project ID using list_projects
2. AI calls list_boards filtered by project_id
3. AI presents board options with task counts

Common Use Cases

• Project Kickoff - Find existing boards before creating new workflows
• Board Bottlenecks - List boards to analyze workflow performance
• Task Management - Find boards to filter tasks by workflow
• Get Board Details - Find board ID before getting full details

Edge Cases

No Boards Found

Situation: Search returns no matches or project has no boards

Response:

{
  "boards": [],
  "total": 0,
  "limit": 50,
  "offset": 0,
  "has_more": false
}

Handling: This is normal - empty array means no boards match. Check if project has boards or try different search terms.

Invalid Project ID

Situation: project_id doesn't exist

Response:

{
  "error": "validation_error",
  "message": "Project with ID 999 not found",
  "field": "project_id"
}

Handling: Verify project_id exists using list_projects first

Permission Denied (403)

Situation: API key doesn't have access to list boards

Response:

{
  "error": "forbidden",
  "message": "You don't have permission to list boards"
}

Handling: Verify API key has access to the workspace

Read 403 troubleshooting guide →

Troubleshooting

Empty Results

Symptom: Returns empty boards array

Causes:

• Project has no boards
• Search query doesn't match any board names
• You don't have access to any boards

Fix:

• Try calling without search parameter to see all boards
• Verify project_id is correct using list_projects
• Check if boards exist in Corcava web interface

Invalid Project ID

Symptom: Validation error about project_id

Causes:

• Project ID doesn't exist
• Project belongs to different workspace
• Project was deleted

Fix:

• Use list_projects to find valid project IDs
• Verify project exists in your workspace
• Omit project_id to list boards across all projects

Best Practices

Using list_boards Effectively

• ✅ Use project_id filter to find boards within a specific project
• ✅ Use search parameter to find boards by name quickly
• ✅ Use pagination (limit/offset) for workspaces with many boards
• ✅ Call get_board after finding board ID for full details
• ✅ Use board IDs from list_boards to filter tasks with list_tasks

Related Tools

Often used together with:

• get_board - Get complete board details after finding ID
• list_projects - Find project IDs before filtering boards
• list_tasks - Filter tasks by board_id from list_boards