MCP Tools Reference

This is the complete reference for all 16 Hypertask MCP tools. Each tool maps to an HTTP API endpoint on https://mcp.hypertask.ai. All requests require a Bearer token in the Authorization header.

Note

All request and response bodies use JSON. Task descriptions and comments use HTML, not Markdown.

---

hypertask_get_user_context

Returns information about the currently authenticated user.

Endpoint: GET /api/mcp/user/context

Parameters: None

Example request:

curl -s -H "Authorization: Bearer $TOKEN" \
  https://mcp.hypertask.ai/api/mcp/user/context

Example response:

{
  "id": 6,
  "email": "valentin@example.com",
  "displayName": "Valentin"
}

---

hypertask_list_projects

List all projects accessible to the current user.

Endpoint: GET /api/mcp/projects

Parameters:

Parameter	Type	Required	Default	Description
status	string	No	Normal	Filter by status: Normal, Archive, Deleted
search	string	No	—	Search projects by name
limit	number	No	50	Max results to return
offset	number	No	0	Pagination offset
sort_by	string	No	title	Sort field: title, createdAt, updatedAt
sort_order	string	No	asc	Sort direction: asc, desc

Example request:

curl -s -H "Authorization: Bearer $TOKEN" \
  "https://mcp.hypertask.ai/api/mcp/projects?status=Normal&limit=10"

Example response:

{
  "projects": [
    {
      "id": 15,
      "title": "Hypertask Product",
      "status": "Normal",
      "createdAt": "2024-11-01T10:00:00Z"
    }
  ],
  "total": 1
}

---

hypertask_create_board

Create a new board, including its sections, labels, and an initial set of tasks, in a single call.

Endpoint: POST /api/mcp/boards

Body parameters:

Parameter	Type	Required	Description
team_id	number	Yes	The team that owns the new board. Find yours via hypertask_get_user_context.
title	string	Yes	Board title
sections	object[]	Yes	Sections (columns) to create. Each: { "title": string }
labels	object[]	No	Labels to pre-create on the board. Each: { "name": string }
tasks	object[]	No	Starter tasks. Each: { "title", "section", "description"?, "priority"?, "labels"?, "assignee_ids"? }

Example request:

curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "team_id": 3,
    "title": "Website Redesign",
    "sections": [
      { "title": "Backlog" },
      { "title": "Doing" },
      { "title": "Done" }
    ],
    "labels": [
      { "name": "Design" },
      { "name": "Frontend" }
    ],
    "tasks": [
      {
        "title": "Wireframe the homepage",
        "section": "Backlog",
        "labels": ["Design"],
        "priority": "high"
      }
    ]
  }' \
  https://mcp.hypertask.ai/api/mcp/boards

Example response:

{
  "board": {
    "id": 42,
    "title": "Website Redesign",
    "sections": [
      { "id": 201, "title": "Backlog" },
      { "id": 202, "title": "Doing" },
      { "id": 203, "title": "Done" }
    ],
    "labels": [
      { "id": 7001, "name": "Design" },
      { "id": 7002, "name": "Frontend" }
    ],
    "tasks": [
      { "id": 9001, "ticketNumber": "WEB-1", "title": "Wireframe the homepage" }
    ]
  }
}

Tip

The CLI wraps this same endpoint via hypertask project create-board —file board.json.

---

hypertask_section (list)

List sections on a project board.

Endpoint: GET /api/mcp/projects/{projectId}/sections

Path parameters:

Parameter	Type	Required	Description
projectId	number	Yes	The project ID

Query parameters:

Parameter	Type	Required	Default	Description
include_hidden	boolean	No	false	Include hidden sections

Example request:

curl -s -H "Authorization: Bearer $TOKEN" \
  https://mcp.hypertask.ai/api/mcp/projects/15/sections

Example response:

{
  "sections": [
    { "id": 101, "title": "Backlog" },
    { "id": 102, "title": "Todo" },
    { "id": 103, "title": "Doing" },
    { "id": 104, "title": "Review" },
    { "id": 105, "title": "Done" }
  ]
}

---

hypertask_section (create)

Create a new section on a project board.

Endpoint: POST /api/mcp/projects/{projectId}/sections

Path parameters:

Parameter	Type	Required	Description
projectId	number	Yes	The project ID

Body parameters:

Parameter	Type	Required	Description
title	string	Yes	Section name (1-200 characters)
after_section_id	number	No	Insert after this section. Omit to append at the end

Example request:

curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  https://mcp.hypertask.ai/api/mcp/projects/15/sections \
  -d '{"title": "QA", "after_section_id": 104}'

Example response:

{
  "id": 106,
  "title": "QA"
}

---

hypertask_list_tasks / hypertask_get_tasks

List tasks with filtering, or retrieve specific tasks by ID.

Endpoint: GET /api/mcp/tasks

Parameters:

Parameter	Type	Required	Description
task_id	number	No	Get a specific task by internal ID
ticket_number	string	No	Get a task by ticket number (e.g. HYP-42)
project_id	number	No	Filter by project
board_id	number	No	Filter by board
section	string	No	Filter by section name
assigned_to	string	No	me, unassigned, or a user ID
priority	string	No	urgent, high, medium, low
status	string	No	Normal, Archive, Deleted
labels	string	No	Comma-separated label names
has_due_date	boolean	No	Filter tasks with/without due dates
due_date_before	string	No	ISO 8601 date
due_date_after	string	No	ISO 8601 date
created_by	number	No	Filter by creator user ID
created_since	string	No	ISO 8601 datetime
updated_since	string	No	ISO 8601 datetime
has_comments	boolean	No	Filter tasks with/without comments
has_attachments	boolean	No	Filter tasks with/without attachments
search	string	No	Simple text search on title
limit	number	No	Max results (default varies)
offset	number	No	Pagination offset

Tip

To get a single task, use task_id or ticket_number. To list tasks on a board, use board_id with optional filters like section and assigned_to.

Example request — list tasks in “Todo” assigned to me:

curl -s -H "Authorization: Bearer $TOKEN" \
  "https://mcp.hypertask.ai/api/mcp/tasks?board_id=15&section=Todo&assigned_to=me"

Example request — get a single task by ticket number:

curl -s -H "Authorization: Bearer $TOKEN" \
  "https://mcp.hypertask.ai/api/mcp/tasks?ticket_number=HYP-42"

Example response:

{
  "tasks": [
    {
      "id": 1234,
      "ticket_number": "HYP-42",
      "title": "Add file upload validation",
      "description": "<p>Validate file types before upload.</p>",
      "priority": "high",
      "section": "Todo",
      "assignees": [
        { "id": 6, "displayName": "Valentin" }
      ],
      "createdAt": "2025-01-15T09:00:00Z",
      "updatedAt": "2025-01-16T14:30:00Z"
    }
  ],
  "total": 1
}

---

hypertask_search_tasks

Full-text search across all accessible tasks. Powered by Typesense for fast, typo-tolerant results.

Endpoint: GET /api/mcp/tasks/search

Parameters:

Parameter	Type	Required	Default	Description
query	string	Yes	—	Search query (max 200 characters)
board_id	number	No	—	Limit search to a specific board
project_id	number	No	—	Limit search to a specific project
section	string	No	—	Filter by section name
assigned_to	string	No	—	me, unassigned, or a user ID
priority	string	No	—	Filter by priority level
has_due_date	boolean	No	—	Filter by due date presence
status	string	No	—	Normal, Archive, Deleted
limit	number	No	10	Max results (max 50)

Example request:

curl -s -H "Authorization: Bearer $TOKEN" \
  "https://mcp.hypertask.ai/api/mcp/tasks/search?query=upload%20validation&board_id=15&limit=5"

Example response:

{
  "tasks": [
    {
      "id": 1234,
      "ticket_number": "HYP-42",
      "title": "Add file upload validation",
      "section": "Todo",
      "priority": "high",
      "score": 0.95
    }
  ],
  "total": 1
}

---

hypertask_create_task

Create a new task in a project.

Endpoint: POST /api/mcp/tasks/create

Body parameters:

Parameter	Type	Required	Description
project_id	number	Yes	Project to create the task in
title	string	Yes	Task title
description	string	No	HTML description
section_id	number	No	Place in a specific section
priority	string	No	urgent, high, medium, low
estimate	number	No	Time estimate (in minutes)
images	string[]	No	Array of image URLs to attach
attachments	string[]	No	Array of file URLs to attach
due_date	string	No	Due date in ISO 8601 format (e.g. 2025-03-01T00:00:00Z)

Caution

labels are not yet supported on task creation via MCP. Use the CLI or the Hypertask UI to set labels.

Example request:

curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  https://mcp.hypertask.ai/api/mcp/tasks/create \
  -d '{
    "project_id": 15,
    "title": "Add error handling to upload endpoint",
    "description": "<p>Return 400 with descriptive error for invalid file types.</p>",
    "priority": "high"
  }'

Example response:

{
  "id": 1235,
  "ticket_number": "HYP-43",
  "title": "Add error handling to upload endpoint",
  "priority": "high",
  "section": "Backlog",
  "createdAt": "2025-01-17T10:00:00Z"
}

---

hypertask_update_task

Update fields on an existing task. The task can be identified by task_id, ticket_number, or the combination of project_id + unique_index.

Endpoint: POST /api/mcp/tasks/update

Task identification (provide one):

Parameter	Type	Description
task_id	number	Internal task ID
ticket_number	string	Ticket number (e.g. HYP-42)
project_id + unique_index	number + number	Project-scoped index

Updatable fields:

Parameter	Type	Description
title	string	New title
description	string	New HTML description
estimate	number	Time estimate in minutes
priority	string	urgent, high, medium, low
sectionId	number	Move to a different section
status	string	Normal, Archive, Deleted
due_date	string	Due date in ISO 8601 format (e.g. 2025-03-01T00:00:00Z)

Caution

labels are not yet supported on task updates via MCP. Use the CLI or the Hypertask UI to set labels.

Example request — move task to “Doing”:

curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  https://mcp.hypertask.ai/api/mcp/tasks/update \
  -d '{
    "ticket_number": "HYP-42",
    "sectionId": 103
  }'

Example response:

{
  "id": 1234,
  "ticket_number": "HYP-42",
  "title": "Add file upload validation",
  "section": "Doing",
  "updatedAt": "2025-01-17T11:00:00Z"
}

---

hypertask_move_task_between_boards

Move a task from its current project to a different project.

Endpoint: POST /api/mcp/tasks/move

Body parameters (identify task with one):

Parameter	Type	Description
task_id	number	Internal task ID
ticket_number	string	Ticket number
unique_index	number	Project-scoped index (requires context)

Target (required):

Parameter	Type	Required	Description
target_project_id	number	Yes	Destination project ID
target_section_id	number	No	Section in the destination project

Example request:

curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  https://mcp.hypertask.ai/api/mcp/tasks/move \
  -d '{
    "ticket_number": "HYP-42",
    "target_project_id": 20,
    "target_section_id": 201
  }'

Example response:

{
  "id": 1234,
  "ticket_number": "HYP-42",
  "project_id": 20,
  "section": "Backlog"
}

---

hypertask_get_comments_for_task

Retrieve comments on a task.

Endpoint: GET /api/mcp/comments

Task identification (provide one):

Parameter	Type	Description
task_id	number	Internal task ID
ticket_number	string	Ticket number
project_id + unique_index	number + number	Project-scoped index

Query parameters:

Parameter	Type	Required	Default	Description
limit	number	No	50	Max comments to return (max 100)
offset	number	No	0	Pagination offset
sort_order	string	No	asc	asc (oldest first) or desc (newest first)

Example request:

curl -s -H "Authorization: Bearer $TOKEN" \
  "https://mcp.hypertask.ai/api/mcp/comments?ticket_number=HYP-42&sort_order=desc&limit=5"

Example response:

{
  "comments": [
    {
      "id": 501,
      "text": "<p>Implemented validation. Returns 400 for unsupported file types.</p>",
      "author": {
        "id": 6,
        "displayName": "Valentin"
      },
      "createdAt": "2025-01-17T12:00:00Z"
    }
  ],
  "total": 1
}

---

hypertask_add_comment_to_task

Add a comment to a task. Comments use HTML formatting.

Endpoint: POST /api/mcp/comments

Body parameters:

Task identification (provide one):

Parameter	Type	Description
task_id	number	Internal task ID
ticket_number	string	Ticket number
unique_index	number	Project-scoped index

Comment content:

Parameter	Type	Required	Description
text	string	Yes	Comment body in HTML
images	string[]	No	Array of image URLs to attach
mentions	object[]	No	Users to mention. Each object: { "user_id": number, "display_name": string }

Caution

@mentions limitation: Mentions added via MCP may appear as plain text and not trigger notifications. Always use the structured mentions parameter (with user_id and display_name) rather than writing @username in the HTML text. Ticket references (e.g. HTPR-1234) in comment text are also not automatically linked to related tasks when added via MCP.

Example request:

curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  https://mcp.hypertask.ai/api/mcp/comments \
  -d '{
    "ticket_number": "HYP-42",
    "text": "<p>Done. Validated against a whitelist of MIME types.</p><ul><li>Added <code>validateFileType()</code> helper</li><li>Returns 400 with error details</li></ul>",
    "mentions": [{ "user_id": 6, "display_name": "Valentin" }]
  }'

Example response:

{
  "id": 502,
  "text": "<p>Done. Validated against a whitelist of MIME types.</p>...",
  "createdAt": "2025-01-17T14:00:00Z"
}

---

hypertask_assign_user

Assign or unassign users on a task. Calling this with an already-assigned user will toggle them off (unassign).

Endpoint: POST /api/mcp/assignees/assign

Body parameters:

Task identification (provide one):

Parameter	Type	Description
task_id	number	Internal task ID
ticket_number	string	Ticket number
unique_index	number	Project-scoped index

Assignment:

Parameter	Type	Description
user_id	number	Single user to assign/unassign
user_ids	number[]	Multiple users (requires mode)
mode	string	Set to multiple when using user_ids

Tip

To find user IDs, call hypertask_list_project_members first.

Example request — assign a single user:

curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  https://mcp.hypertask.ai/api/mcp/assignees/assign \
  -d '{
    "ticket_number": "HYP-42",
    "user_id": 6
  }'

Example request — assign multiple users:

curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  https://mcp.hypertask.ai/api/mcp/assignees/assign \
  -d '{
    "task_id": 1234,
    "user_ids": [6, 836],
    "mode": "multiple"
  }'

Example response:

{
  "assignees": [
    { "id": 6, "displayName": "Valentin" },
    { "id": 836, "displayName": "Claude" }
  ]
}

---

hypertask_list_project_members

List all members of a project with their user IDs.

Endpoint: GET /api/mcp/projects/{projectId}/members

Path parameters:

Parameter	Type	Required	Description
projectId	number	Yes	The project ID

Example request:

curl -s -H "Authorization: Bearer $TOKEN" \
  https://mcp.hypertask.ai/api/mcp/projects/15/members

Example response:

{
  "members": [
    {
      "id": 6,
      "email": "valentin@example.com",
      "displayName": "Valentin",
      "photoURL": "https://example.com/avatar.jpg"
    },
    {
      "id": 836,
      "email": "claude@example.com",
      "displayName": "Claude",
      "photoURL": null
    }
  ]
}

---

hypertask_inbox_list

Get inbox notifications for the current user. Notifications are generated when you are assigned to a task, mentioned in a comment, or a task you are watching is updated.

Endpoint: GET /api/mcp/inbox/list

Parameters: None

Example request:

curl -s -H "Authorization: Bearer $TOKEN" \
  https://mcp.hypertask.ai/api/mcp/inbox/list

Example response:

{
  "notifications": [
    {
      "id": 301,
      "type": "assignment",
      "task_id": 1234,
      "ticket_number": "HYP-42",
      "message": "You were assigned to 'Add file upload validation'",
      "createdAt": "2025-01-17T08:00:00Z",
      "read": false
    }
  ],
  "total": 1
}

---

hypertask_inbox_archive

Archive (dismiss) inbox notifications.

Endpoint: POST /api/mcp/inbox/archive

Body parameters:

Parameter	Type	Required	Description
notification_ids	number[]	Yes	Array of notification IDs to archive

Example request:

curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  https://mcp.hypertask.ai/api/mcp/inbox/archive \
  -d '{"notification_ids": [301, 302]}'

Example response:

{
  "archived": 2
}