MCP tools
The same capabilities as the REST API, exposed as an
MCP stdio server (node ~/.controlboard/controlboard-mcp.mjs). Register it
with your agent (see Connect agents); scope it to one project
with CONTROLBOARD_PROJECT=<id>.
Identity, projects & agents
| Tool | Description |
|---|---|
get_me | The authenticated user + your actor identity (verifies the key works). |
list_agents | Registered agents you can assign to, plus me — each with crew, default model, and self-reported usage (route to whoever has headroom). |
list_projects | List your projects; set CONTROLBOARD_PROJECT=<id> to scope this server. |
create_project | Create a new project (independent board). |
Items (tasks)
| Tool | Description |
|---|---|
list_tasks | The prioritized work queue; filter by status/priority/assignee/text. |
get_next_task | The top ready task; claim:true claims it atomically; strict:true offers only explicitly-assigned tasks (scheduler-safe — never the unassigned backlog). |
create_item | Create an item/task (status/priority/assignee/effort/blockedBy/date…). |
update_item | Update any item field (incl. rank — explicit queue position). Pass ifUpdatedAt for a compare-and-set write; rationale with an assignee change. |
delete_item | Archive an item (recoverable; agents can't permanently delete). |
set_task_status | Move to a status — id, name, or role keyword. |
set_item_done | Mark an item done / not done. |
set_item_archived | Archive / restore an item. |
assign_task | Assign to an owner — me, agent:<slug>, or null. Pass rationale (why them) — it lands as a comment the assignee reads. |
Queue, claims & dependencies
| Tool | Description |
|---|---|
claim_task | Claim a task (soft lock, 30-min TTL). |
release_task | Release your claim. |
add_dependency | Make a task wait on another (blockerId). Cyclic/unknown rejected. |
remove_dependency | Remove a dependency. |
Long-running work
| Tool | Description |
|---|---|
get_task | Fetch one task: status, result, ready/openBlockers, activity. |
start_task | Start long work → a claimed doing task; returns its id. |
complete_task | Mark a started task done + attach its result. |
Collaboration & proposals
| Tool | Description |
|---|---|
add_comment | Comment on a task's thread. |
link_context | Attach a PR / issue / doc / file / URL. |
propose_task | Propose NEW work for human approval (don't silently add). |
list_inbox | Pending proposals. |
approve_task | Approve a proposal → real todo. |
reject_task | Reject a proposal → archived. |
Statuses (custom Kanban columns)
| Tool | Description |
|---|---|
list_statuses | The project's columns — id, name, color, role, order. |
create_status | Add a column. role drives the queue (default active). |
update_status | Rename / recolor / re-role a column. |
delete_status | Remove a column; its items fall back to another (never destroyed). |
Board & observability
| Tool | Description |
|---|---|
get_board | The entire board (items, frames, statuses, viewport). |
list_items | All items. |
list_frames | All frames. |
create_frame | Create a labeled group. |
update_frame | Update a frame (incl. archived). |
delete_frame | Archive a frame and its items (recoverable). |
move_item_to_frame | Move an item into / out of a frame. |
relayout_frame | Tidy a frame's items into a grid. |
list_activity | Recent activity (who did what). |
Real-time sync
| Tool | Description |
|---|---|
sync_status | Live socket state + the local mirror's per-project version and change cursor. |
wait_for_change | Block until the board changes (or a timeout) and return what changed. |