MCP Tools Reference

HPI provides an MCP (Model Context Protocol) server that AI agents can use to create tasks and interact with humans. This is ideal for AI systems like Claude that support MCP.

Quick Actions

These tools handle common patterns with a single call:

ask_question

Ask a human a free-text question and wait for their answer.

{
	"question": "What is the expected deployment date?",
	"context": "The staging environment is ready...",
	"timeout_seconds": 300
}

ask_approval

Request yes/no approval with an optional comment field.

{
	"title": "Merge PR #42",
	"details": "Changes include...",
	"timeout_seconds": 300
}

ask_choice

Present multiple options and wait for a selection.

{
	"question": "Which database should we use?",
	"choices": ["PostgreSQL", "MySQL", "SQLite"],
	"context": "Considering performance requirements..."
}

ask_for_review

Present content for review with a verdict selector (Approve / Request Changes / Comment).

{
	"title": "Code review: auth module",
	"content": "```python\ndef authenticate(user):\n    ...\n```"
}

Task Management

create_task

Create a task with full control over steps and blocks. Set wait: true to hold until the human completes the task and return the result inline — no need for a separate wait_for_task call.

{
	"title": "Approve deployment",
	"assignee_member_id": "me",
	"wait": true,
	"timeout_seconds": 300,
	"steps": [
		{
			"id": "approval",
			"title": "Review",
			"blocks": [
				{
					"type": "input",
					"field": { "name": "approved", "label": "Approve?", "kind": "checkbox" }
				}
			]
		}
	]
}

Returns the task metadata plus status, data, and fail_reason when wait is true.

Supports sinks for webhook, NATS, and email notifications. See Create Task for the full schema and Notification Sinks for sink configuration details.

wait_for_task

Wait for an existing task to reach a terminal state (completed, failed, cancelled). Uses long-polling — the server holds the connection open until the task completes or the timeout expires. Useful when the task was created earlier or by a different system.

get_task

Retrieve a task by ID. Set include_definition: true to also return the full task definition (steps, blocks, and instructions).

list_tasks

List tasks with filtering, search, sorting, and pagination.

cancel_task

Cancel a pending task.

Process Management

create_process

Create a tracked process with step definitions.

get_process

Retrieve process details including timeline.

update_process

Push step transitions and progress updates.

list_processes

List processes with filtering, search, sorting, and pagination.

Rich Content

send_image

Upload an image and create a task that displays it for human review.

{
	"title": "Review this mockup",
	"image_path": "/path/to/mockup.png",
	"message": "Does this layout look correct?"
}

send_document

Upload a document (PDF, etc.) and create a review task.

{
	"title": "Review: Q4 Report",
	"file_path": "/path/to/report.pdf",
	"message": "Please review the quarterly numbers"
}

upload_file

Upload a file and get a URL for use in task blocks.

Task Builder

For complex tasks with multiple block types, use the builder pattern:

begin_task

Start building a draft task. Returns a draft_id.

add_md

Add a markdown content block.

add_image

Upload and add an image block.

add_file

Upload and add a file block.

add_input

Add a form input field.

add_callout

Add a callout/alert block.

add_table

Add a data table block.

submit_task

Submit the draft task and wait for the human to respond.

Example: Builder Pattern

1. begin_task({ title: "Review deployment plan" })
   → draft_id: "abc"

2. add_md({ draft_id: "abc", content: "## Deployment Plan\n..." })

3. add_table({ draft_id: "abc", headers: ["Service", "Version"], rows: [...] })

4. add_callout({ draft_id: "abc", severity: "warning", content: "This will cause 2 minutes of downtime" })

5. add_input({ draft_id: "abc", name: "approved", label: "Approve?", kind: "checkbox" })

6. submit_task({ draft_id: "abc" })
   → waits for human response
   → returns { approved: true }