Get a Single Task via MCP: Fields, Status, and Context

Developer reference for the get_task MCP tool. Learn how to retrieve complete details of a specific task including all fields, status, comments, and metadata. Includes example tool calls, natural language prompts, edge cases, and troubleshooting.

Tool Overview

Purpose

The get_task tool retrieves complete details of a specific task by its ID. Use this tool when you need full context about a task before making updates, reviewing its history, or preparing handoffs.

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

Input Parameters

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

Output Format

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

{
  "id": 123,
  "title": "Implement login feature",
  "description": "Add user authentication with email/password and OAuth support",
  "status": "in_progress",
  "priority": "high",
  "due_date": "2026-02-28",
  "project_id": 456,
  "board_id": 789,
  "assignee_id": 101,
  "assignee_name": "John Doe",
  "created_at": "2026-01-15T10:30:00Z",
  "updated_at": "2026-02-20T14:22:00Z",
  "created_by_id": 99,
  "comments": [
    {
      "id": 1,
      "content": "Started working on OAuth integration",
      "author_id": 101,
      "author_name": "John Doe",
      "created_at": "2026-02-20T14:22:00Z"
    }
  ],
  "tags": ["authentication", "backend"],
  "estimated_hours": 8,
  "actual_hours": 4.5
}

Response Fields

• id: Unique task identifier
• title: Task title/name
• description: Full task description
• status: Current status (open, in_progress, done, blocked)
• priority: Task priority (low, medium, high, urgent)
• due_date: Due date in ISO format (YYYY-MM-DD) or null
• project_id: ID of the project this task belongs to
• board_id: ID of the board this task is on
• assignee_id: ID of the user assigned to this task
• assignee_name: Name of the assigned user
• created_at: Timestamp when task was created
• updated_at: Timestamp when task was last updated
• created_by_id: ID of the user who created the task
• comments: Array of comment objects with content, author, and timestamps
• tags: Array of tag strings
• estimated_hours: Estimated time to complete (if set)
• actual_hours: Actual time logged (if tracked)

Example Tool Calls

Example 1: Get Task by ID

Tool Call (JSON):

{
  "tool": "get_task",
  "arguments": {
    "task_id": 123
  }
}

Returns: Complete task object with all fields

Natural Language Prompt Examples

Here's how users typically interact with get_task through natural language:

Claude Desktop / General AI

User Prompt:

"Show me details for task #123"

AI Behavior:

1. AI calls get_task with task_id: 123
2. AI receives complete task object
3. AI formats and presents task details to user

Cursor / IDE Context

User Prompt:

"What are the acceptance criteria for the login feature task?"

AI Behavior:

1. AI finds task using list_tasks with search: "login feature"
2. AI calls get_task with the task ID
3. AI extracts acceptance criteria from description or comments
4. AI presents criteria in IDE-friendly format

Preparing for Updates

User Prompt:

"Show me the current state of task #456 before I update it"

AI Behavior:

1. AI calls get_task to read current state
2. AI shows current task details
3. AI waits for user to specify changes
4. AI can then show diff before calling update_task

Common Use Cases

• Task Handoff - Get complete task context for handing off to a new owner
• Acceptance Criteria - Review task details to propose or verify acceptance criteria
• Task Management - Review task details before making updates or changes
• Pre-Update Review - Read current state before updating task fields

Edge Cases

Task Not Found (404)

Situation: Task ID doesn't exist or was deleted

Response:

{
  "error": "not_found",
  "message": "Task with ID 123 not found"
}

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

Permission Denied (403)

Situation: Task exists but you don't have access

Response:

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

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

Read 403 troubleshooting guide →

Invalid Task ID

Situation: Task ID is not a valid integer

Response:

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

Handling: Ensure task_id is a valid integer

Troubleshooting

Invalid Task ID

Symptom: 400 validation error or 404 not found

Causes:

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

Fix:

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

Access Denied (403)

Symptom: 403 Forbidden error

Causes:

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

Fix:

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

Read 403 troubleshooting guide →

Best Practices

Using get_task Effectively

• ✅ Always call get_task before update_task to read current state
• ✅ Use get_task to verify task exists before attempting updates
• ✅ Review task comments to understand context and history
• ✅ Check task status before making status changes
• ✅ Use task details to prepare handoffs and summaries
• ✅ Verify task belongs to expected project/board before operations

Related Tools

Often used together with:

• list_tasks - Find task IDs before calling get_task
• update_task - Read task details before updating
• list_task_comments - Get detailed comment history (get_task includes recent comments)