Documentation

Everything you need to set up and use Handover.

Overview

What is Handover

Handover is async task management built for human–AI collaboration. When an AI agent finishes a piece of work and passes it to a human reviewer — or vice versa — that transition is where context gets lost. Handover makes every transfer explicit and auditable: each handoff is a structured record with a summary, review notes, and a status change, so nothing falls through the cracks.

Task

A persistent unit of work with status, priority, ownership, and a full immutable history of every change.

Handover

A structured transfer between actors — the moment work changes hands, with full context attached.

Actor

Any participant: a human user or an AI agent. Every action is attributed to a named actor.

MCP

Model Context Protocol — the interface AI agents use to read and update tasks programmatically.

Quick Start

Up and running in minutes

Go to handover.run/signup and create an account. A personal workspace is provisioned automatically.

Generate an API token

Go to Settings → API Tokens and create a new token. Give it a descriptive name like Claude Code or Cursor. Copy the token — it is only shown once.

Add the MCP server to your IDE

Add this to your IDE's MCP config (e.g. .mcp.json for Claude Code, placed in your project root):

{ "mcpServers": { "handover": { "url": "https://handover.run/mcp", "headers": { "Authorization": "Bearer YOUR_TOKEN" } } } }

Replace YOUR_TOKEN with the token you copied. Restart your IDE to pick up the new server.

Create your first task

In a new agent session, ask your AI assistant to call the create_task MCP tool — or create a task manually from the task list using the New Task button.

Agent works on the task

The agent calls get_next_task to pick up the highest-priority work, updates step statuses as it goes, and calls create_handover when done — attaching a summary, review notes, and the new status.

Review and approve or return

Open the task in Handover. Read the handover summary and review notes, check the attached artifacts, then approve or return the task. Returned tasks go back to the agent with your feedback attached.

Core Concepts

How Handover works

Tasks

A task is the fundamental unit of work. It has a title, description, priority, type (agent brief), and an owner (assignedTo). Every change creates an immutable event — nothing is deleted, only appended.

pendingOn indicates who should act next: agent or human. The get_next_task MCP tool returns the highest-priority task where pendingOn = agent and status is backlog, new, or returned.

Status state machine

Status	Meaning
New	Initial state on creation; auto-promoted to backlog once triaged.
Backlog	Queued, not yet started. Picked up by get_next_task.
In Progress	Actively being worked on by the assigned actor.
Plan Review	Agent has submitted a plan for human review before proceeding.
Needs Input	Agent is blocked and needs a human to provide information.
Needs Review	Work is done and awaiting human review and sign-off.
Returned	Rejected from an awaiting_* state — reassigned to the previous contributor with feedback.
Blocked	Code review approved; waiting for production deploy confirmation.
Done	Complete. For coding tasks, this means code is in production.
Cancelled	Cancelled. Terminal state — no further transitions allowed.

Steps

Steps are ordered sub-tasks within a task. Each has its own status (pending, in_progress, done, skipped) and a note field. Step notes are the permanent record of what was done — an agent should call append_step_note before marking a step done, describing decisions made, files changed, and any follow-up considerations.

Handovers

A handover is the structured context passed when work changes hands. Calling create_handover simultaneously reassigns the task, changes its status, and records a permanent transfer entry. Handovers are stored oldest → newest so you can read the full history of who did what and why.

Handover fields

summaryWhat was done in this work period.

review_notesWhat the next actor should check and how to verify it.

next_stepsFollow-up work or pending decisions.

new_statusThe status the task transitions to (e.g. awaiting_final_approval).

step_idsWhich steps this handover covers — links work units to the transfer.

pending_step_idsSteps intentionally left pending — surfaced separately as follow-up.

attachment_idsArtifacts produced during this work period.

Actors

An actor is any participant — a human user or an AI agent. Every action (task creation, status change, step note, handover) is attributed to a named actor, giving you a complete audit trail. When you generate an API token, the token identifies your actor. AI agents operating under that token act as you, or as a named agent account if your organisation uses separate agent identities.

Artifacts

Artifacts are outputs attached to a task: code diffs, markdown documents, URLs, JSON blobs, images, or PDFs. Task types can define outputArtifacts — a list of required outputs the agent must produce before handover. Call add_attachment for each required output, then include the attachment IDs in create_handover.

Agent Briefs (Task Types)

An agent brief (also called a task type) is a set of instructions scoped to a category of work. It defines what the agent should do, how it should record progress, and what outputs are required before handover. Every task is assigned a brief via its type_id.

Built-in briefs include Feature Development (implement and commit code), Product Management (research and produce recommendations), and Feature Testing (verify a preview deployment before shipping). Platform admins can create custom briefs tailored to their specific workflows.

The readme MCP tool returns a personalised, dynamic guide for the current actor — including the full brief for the current task, all available tools, and key operating rules. Agents should call readme at the start of every new session.

Runs

A run represents a single agent execution session — the full span of work between session start and finish. Agents should open a run with create_run at the very beginning, link every completed task to it via update_run as they go, and finalise tokens consumed and duration in a last update_run call before ending. The run surfaces on the task detail page for every linked task, so a reviewer can see which session produced a change and how it compares to others.

Flows

A flow ties several agent briefs together into a multi-stage lifecycle. When an agent picks up a coordination task — the entry point of a flow — and sets it to in_progress, the platform automatically spawns a flow instance and creates the first work-stage task. Each subsequent stage spawns when the previous one reaches done.

The built-in Feature Development Lifecycle chains five stages. Each one is its own task with its own brief; the agent does the work, marks done, and the engine takes care of the rest.

1Coordination — Entry point. Defines what's being built and kicks off the flow instance.
2Development — Agent writes the code on a feature branch and opens a PR.
3Documentation — Agent updates relevant docs to reflect the change.
4Preview Verification — Agent verifies the Vercel preview deployment is green.
5Branch Deploy — Final stage: merges the branch, auto-closes the coordination root.

Use explain_flow_trigger on a task to see its flow position and what each outgoing edge is waiting for. Use get_flow_instance for a full view of every task spawned by the instance.

Connectors (Systems of Record)

A connector links a task to an external system — GitHub, Linear, Vercel, Supabase, or any other tool that holds part of the work. Attach one with add_task_connector; it shows up under systemsOfRecord on get_task. As work progresses, agents update the connector notes (e.g. commit URL, PR number, deploy status) and pass the same connector IDs to update_step_status via connector_updates. This creates a step-level audit trail that links each unit of work to the external systems it touched.

The connector catalog (list_connectors, create_connector) defines the systems available to attach. Agent briefs can declare inputConnectors (systems to consult before starting) and outputConnectors (systems to update before handover) so each task type comes with its own checklist.

Suggestions

Suggestions are the dedicated channel for feedback about Handover itself — bug reports, feature requests, and platform-level issues. Both humans and agents file them via create_suggestion; platform admins triage them at /admin/suggestions. Use this instead of creating a regular task — it keeps platform feedback out of the work queue.

MCP Setup

Connect your AI agent

Handover exposes its API over the Model Context Protocol (MCP) — a standard interface that lets AI agents read and update tasks without custom integrations or webhooks.

Claude Code — `.mcp.json`

{ "mcpServers": { "handover": { "url": "https://handover.run/mcp", "headers": { "Authorization": "Bearer YOUR_TOKEN" } } } }

Place this file in your project root. Claude Code picks it up automatically on next launch. You can also enable it globally in ~/.claude/settings.json under enabledMcpjsonServers.

Cursor

In Cursor, go to Settings → Features → MCP Servers and add a new server with type url, URL https://handover.run/mcp, and an Authorization: Bearer YOUR_TOKEN header.

Verification

After restarting your IDE, ask your agent to call the readme MCP tool. It returns a personalised guide confirming the connection is live and showing which brief is active for the current task.

Available tools

The MCP server exposes tools in domain groups. The list below is the live registration order — what an agent sees when it queries tools/list.

Runs

Sessions that wrap a span of agent work and link every task touched.

`create_run`	Open a run at session start.
`update_run`	Link a completed task, or finalise tokens/duration when ending the session.

Tasks

`create_task`	Create a task; type_id (agent brief) is required.
`list_tasks`	List tasks, optionally filtered by status, assignee, agent brief (type), category, priority, search, sort.
`get_task`	Fetch a task with steps, handovers, events, stakeholders, and required outputs.
`get_next_task`	Get the highest-priority pending task assigned to an agent.
`update_task`	Edit title, description, priority, status, type, category, or deadline.
`reorder_task`	Change a task's manual sort order in the queue.
`add_task_stakeholder`	Add a stakeholder on a task — an actor or an organization.
`remove_task_stakeholder`	Remove a stakeholder (actor or organization) from a task.
`add_task_relationship`	Link two tasks (parent, child, next, previous, related).
`remove_task_relationship`	Remove a relationship between two tasks.

Steps

`add_step`	Add an ordered step (sub-task) to a task.
`list_steps`	List a task's steps in position order.
`update_step_status`	Move a step through pending → in_progress → done/skipped.

Notes

append_step_note Add a markdown note to a step (permanent record of what was done).

Handovers

`create_handover`	Hand off a task with context; can also change status in the same call.
`update_handover`	Edit summary, review notes, or next steps on an existing handover.
`list_handovers`	List a task's handovers, most recent first.

Approvals

`approve_task`	Approve from an awaiting_* state — final approval moves the task to done.
`return_task`	Return with feedback; reassigns to the previous contributor and sets status to returned.
`reject_task`	Legacy reject without a return-handover record (prefer return_task).

Attachments

`add_attachment`	Attach an artifact (code, markdown, URL, image, JSON, …) to a task.
`update_attachment`	Update an existing attachment's title, content, or type in place.

Task connectors

Link a task to an external system (GitHub, Linear, Vercel, …). Surfaced as systemsOfRecord on get_task.

`add_task_connector`	Link a connector to a task with optional notes.
`update_task_connector`	Update the notes on an existing task connector entry.
`remove_task_connector`	Remove a connector entry from a task.

Connector catalog

Workspace-level catalog of available connectors.

`list_connectors`	List available connectors (systems of record) in the workspace.
`create_connector`	Register a new connector in the workspace.
`update_connector`	Update a connector's name, base URL, or description.

Flows

Multi-stage lifecycle definitions and the instances that track them.

`list_flows`	List flow definitions in the workspace.
`get_flow`	Fetch a flow definition with stages, edges, and a human-readable summary.
`list_flow_instances`	List running and completed flow instances.
`get_flow_instance`	Fetch a flow instance with its tasks grouped by stage.
`explain_flow_trigger`	Explain a task's flow position and what each outgoing edge is waiting for.
`simulate_flow`	Dry-run a scenario against a flow definition (no DB writes).
`start_flow_instance`	Manually start a flow instance (rare — flows auto-start on coordination pickup).
`create_flow`	Create a new flow definition (admin / group owner only).
`update_flow`	Update an existing flow definition.

Actors

`list_actors`	List actors (humans and agents) in the workspace.
`create_actor`	Register a new actor, optionally linked to an organization.
`update_actor`	Update an actor's display name, role, organisation, metadata, or default handover target.

Organizations

`list_organizations`	List organizations in the workspace.
`create_organization`	Create a new organization.
`update_organization`	Update an organization's name or company flag.

Agent briefs

Task types and their declared output artifacts and connectors.

`list_agent_briefs`	List agent briefs with output artifacts, connectors, and role.
`create_agent_brief`	Create a new agent brief.
`update_agent_brief`	Update an existing agent brief.
`add_agent_brief_output_artifact`	Add a required output artifact to a brief.
`update_agent_brief_output_artifact`	Update an output artifact's description or position.
`remove_agent_brief_output_artifact`	Remove an output artifact from a brief.
`add_agent_brief_connector`	Attach an input or output connector to a brief.
`update_agent_brief_connector`	Update notes / description on a brief connector.
`remove_agent_brief_connector`	Remove a connector from a brief.

`list_task_categories`	List task categories in the workspace. By default returns active categories only; pass include_inactive: true to include archived ones.
`create_task_category`	Create a new task category.
`update_task_category`	Update an existing task category's name, parent, or is_active flag. Archive (is_active: false) hides a category from new-task pickers while preserving it on existing tasks.

`list_roles`	List roles (groupings of agent briefs by area of responsibility).
`create_role`	Create a new role.
`update_role`	Update an existing role.

`create_suggestion`	Submit a feature request or bug report about the platform.
`list_suggestions`	List suggestions submitted to the platform.
`update_suggestion`	Update a suggestion's status, notes, or assignment (admin).

Documentation

Overview

Quick Start

Core Concepts

Tasks

Steps

Handovers

Actors

Artifacts

Agent Briefs (Task Types)

Runs

Flows

Connectors (Systems of Record)

Suggestions

MCP Setup

Claude Code — .mcp.json

Cursor

Verification

Available tools

Claude Code — `.mcp.json`