Docs / Reference

MCP tools reference

The remote MCP server is https://taskhold.com/api/mcp (Streamable HTTP, stateless), authenticated with the header Authorization: Bearer atd_sk_... It serves 19 tools. Tool results are plain text written for the agent, and every error says what to do next.

Live progress tools

Live progress tools
Tool	Arguments	Use it to
taskhold_plan	task_id, steps (strings or {title, description}, 1 to 50), replace?	Break a task into ordered steps. Returns the checklist with step ids.
taskhold_progress	task_id, percent? (0-100), current?, total?, message?	Move the bar inside a step or a step-less task. Give at least one of percent, total or message.
taskhold_updates	since? (cursor), include_agent?	Read what the person changed since the cursor: replies, new tasks, priority changes, unblocks.

Work tools

Work tools
Tool	Arguments	Use it to
taskhold_get_current	none	See the task in progress, its steps and the next one. Call at session start.
taskhold_list	status?, priority?, project_id?, limit? (default 20)	List top-level tasks grouped by status.
taskhold_get	task_id	Read one task with description, steps, notes and summary.
taskhold_search	query, status?	Find tasks by text in title or description.
taskhold_start	task_id, agent?	Mark a task or step in progress. agent is the label shown on the board.
taskhold_complete	task_id, summary?	Finish a task or step. Completing a step returns the next one.
taskhold_block	task_id, reason	Stop and ask the person. The reason shows at the top of the board.
taskhold_unblock	task_id	Move a blocked task back to todo.
taskhold_add_note	task_id, note	Leave a finding or decision on the task's timeline.
taskhold_create	title, description?, priority?, project_id?, labels?, parent_task_id?	File new work, or one step with parent_task_id.
taskhold_create_from_todo	title, file_path, line_number, description?	File a TODO comment with its location.
taskhold_update	task_id, title?, description?, priority?, project_id?	Edit a task.
taskhold_set_priority	task_id, priority	Change priority (low, medium, high, urgent).
taskhold_list_projects	none	List projects.
taskhold_list_labels	none	List labels.
taskhold_get_summary	none	Counts by status, priority and who added them.

Example: report progress

A tools/call request over plain HTTP, the same thing an MCP client sends:

curl -s https://taskhold.com/api/mcp -H "Authorization: Bearer API_KEY" \
  -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"taskhold_progress",
       "arguments":{"task_id":"TASK_ID","current":3,"total":5,"message":"Building api image"}}}'

The text the agent gets back:

Progress on "Build images": [############--------] 60%
Now: Building api image

Example: read replies

- [2026-10-26T05:30:12.004Z] Human on "Send receipts from the new domain": Send from mail.example.com; the DNS records are in. (task c61740dd-...)

Cursor: 41 (pass as since next time)

taskhold_updates with since: 38. Without since, the latest 20 changes.

Errors

Tool errors come back as isError results whose text names the problem and the next call: a task id that doesn't exist names taskhold_list, a missing key or subscription comes back as the 401 or 402 message from /docs/troubleshooting.