Start Time Tracking via MCP: Linking Work Sessions to Tasks

Developer reference for the start_time_tracking MCP tool. Learn how to start a timer for a task, prevent multiple timers, and use confirmation patterns. Includes safety checks, example tool calls, natural language prompts, edge cases, and troubleshooting.

Tool Overview

Purpose

The start_time_tracking tool starts a timer for a specific task. Use this tool to track time spent on work, link coding sessions to tasks, or begin focus sessions. Only one timer can run at a time per workspace.

⚠️ Write operation: This tool modifies data - always use confirmation patterns and check for existing timers before calling it.

Input Parameters

The tool requires a task ID to start tracking.

Output Format

The tool returns the tracking status object:

{
  "task_id": 123,
  "task_title": "Implement login feature",
  "started_at": "2026-03-19T10:30:00Z",
  "is_running": true
}

Safety Checks and Confirmation Patterns

⚠️ Always Check for Existing Timer First

Never let AI start a timer without checking for existing timers. Use these patterns:

• Check Status First: Call get_tracking_status to check if a timer is already running
• Stop Existing Timer: If a timer is running, stop it first or ask user to confirm
• Confirm Task: Show task title and ID before starting timer
• Confirmation Token: Require "CONFIRM" before calling start_time_tracking

Learn more about safe write workflows →

Safe Prompt Pattern

✅ Safe Prompt Template:

"I want to start tracking time on task #123. 
First, check if any timer is already running. 
If yes, ask me if I want to stop it first. 
Then show me the task title and wait for CONFIRM before starting the timer. 
If I don't type CONFIRM, don't start anything."

Example Tool Calls

Example 1: Start Timer

Tool Call (JSON):

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

Returns: Tracking status with task_id, task_title, started_at, and is_running=true

Natural Language Prompt Examples

Safe Timer Start with Status Check

User Prompt:

"Start tracking time on the login feature task. Check if any timer is running first."

AI Behavior:

1. AI calls get_tracking_status to check for existing timer
2. If timer exists, AI warns: "Timer already running on task X. Stop it first?"
3. If no timer, AI finds task using list_tasks or get_task
4. AI shows: "Starting timer on: Login Feature (task #123)"
5. AI waits for "CONFIRM"
6. AI calls start_time_tracking only after confirmation

Starting Work Session

User Prompt:

"I'm starting work on task #456. Start the timer, but check for existing timers first."

AI Behavior:

1. AI checks get_tracking_status
2. AI verifies task #456 exists using get_task
3. AI shows preview and asks for confirmation
4. After confirmation, AI starts timer

Common Use Cases

• Time Tracking Basics - Start timers when beginning work on tasks
• Editor Workflow - Link coding sessions to tasks via timers
• Daily Focus - Start timer on top priority task for the day
• Check Status First - Always check for existing timers before starting

Edge Cases

Timer Already Running

Situation: A timer is already running for another task

Response:

{
  "error": "timer_already_running",
  "message": "Timer is already running for task 456",
  "current_task_id": 456,
  "current_task_title": "Previous Task",
  "started_at": "2026-03-19T09:00:00Z"
}

Handling: Stop the existing timer first using stop_time_tracking, then start new timer

Task Not Found (404)

Situation: task_id doesn't exist

Response:

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

Handling: Verify task ID is correct

Permission Denied (403)

Situation: Task exists but you don't have permission to track time

Response:

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

Handling: Check task permissions in Corcava

Read 403 troubleshooting guide →

Troubleshooting

Timer Already Running

Symptom: Error about timer already running

Causes:

• Another timer is active for a different task
• Previous timer wasn't stopped

Fix:

• Call get_tracking_status to see current timer
• Call stop_time_tracking to stop existing timer
• Then call start_time_tracking for new task

Task Not Found (404)

Symptom: 404 Not Found error

Causes:

• Task ID doesn't exist
• Task was deleted
• Invalid task_id format

Fix:

• Verify task_id is correct
• Use list_tasks or get_task to find valid IDs
• Check if task still exists

Best Practices

Using start_time_tracking Safely

• ✅ Always call get_tracking_status first to check for existing timers
• ✅ Stop existing timer before starting a new one (or ask user to confirm)
• ✅ Verify task exists using get_task before starting timer
• ✅ Show task title and ID to user before starting
• ✅ Require explicit confirmation (CONFIRM token)
• ✅ Use stop_time_tracking when switching tasks or ending work

Related Tools

Often used together with:

• get_tracking_status - Check for existing timers before starting
• stop_time_tracking - Stop timer when switching tasks or ending work
• get_task - Verify task exists before starting timer
• Least-Privilege Workflows - Safe write workflow patterns