# MCP tools reference

> Every Taskhold MCP tool: what it does, its arguments, what it returns and when an agent should call it. Remote server at taskhold.com/api/mcp.

Source: https://taskhold.com/docs/mcp-tools
Last updated: 2026-10-26

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

| 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

| 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:

```bash
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:

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

## Example: read replies

```text
- [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.

## Related

- [Taskhold REST API: tasks, steps, progress, curl examples](https://taskhold.com/docs/rest-api.md)
- [How live progress works: steps, bars, ETA and liveness](https://taskhold.com/docs/live-progress.md)
- [How agents should write progress notes and questions](https://taskhold.com/docs/agent-messages.md)