MCP tool reference
Every tool the Masaro MCP server exposes. Your agent discovers these automatically on connect; this page is for humans who want to know exactly what a connected agent can and can't do.
All tools operate inside the single workspace the connection was authorized for. There is no cross-workspace access on one connection.
Context: reading the board
| get_workspace_context | The workspace at a glance: statuses, labels, complexity vocabulary, your projects, and the active cycle (its goal and end date) when cycles are on. The standard first call of a session. |
|---|---|
| get_project_context | Deeper context for one project: its memory, conventions, and decisions. |
| list_tasks | Filter or search tasks by query, status, epic, label, assignee, or what’s assigned to you. cycleId narrows to one time-box, and the literal "active" means whichever cycle is running now. Searches the whole workspace by default — including tasks that belong to no project — or one project when narrowed. Paginated with a string cursor. |
| get_task | One task in full: description, acceptance criteria, dependencies, optional comments, activity. Plus pendingSuggestions — AI proposals nobody has accepted yet, where the criteria drafted at claim time sit — and the workspacePolicy the calling agent works under. Accepts a UUID or workspace identifier. |
| get_next_task | The next workable task: unclaimed, unblocked, highest priority first. Selects across the whole workspace by default — project-less tasks included. Ready tasks win; if Ready is empty, Backlog tasks that already have acceptance criteria are eligible. A task a human explicitly assigned to the calling agent beats both pools, and within every pool tasks in the active cycle sort first. Returns the workspacePolicy too: supervised or not, sign-off before merge or not. The “give me work” call. |
Work: the execution loop
| claim_task | Take a task. Moves it to In Progress under the agent's identity; prevents duplicate pickup; adds it to the active cycle if one is running. If the task had neither a summary nor criteria the reply says prepQueued: Masaro is drafting them in the background, and the agent re-reads the task a moment later. |
|---|---|
| update_progress | Report a meaningful chunk of progress (setup, core implementation, tests, PR opened). Lands on the activity feed; doubles as the liveness heartbeat. |
| complete_task | Deliver: a summary plus an optional met/not-met mapping per acceptance criterion. Moves the task to In Review; returns any tasks that became unblocked. |
| report_blocker | Stuck on something needing human input. Notifies you immediately with specific unblocking questions. |
| release_task | Put a claimed task back to Ready without completing it: clean hand-back, no zombie claim. |
Authoring: proposing work
| create_task | Create a task: title, summary, description, criteria, complexity, priority, labels, due date, epic, cycleId, assignee by name or email, and parentId to nest a subtask. Top-level tasks land in Triage for your accept/decline; subtasks land in the backlog. A project is optional — leave projectId out and the task belongs to no project. |
|---|---|
| update_task | Edit an existing task’s fields, including moving it between projects (or out of one — pass projectId: null) and in or out of a cycle (cycleId: null takes it out). Status moves are limited to triage, backlog, and ready; in-flight transitions go through claim_task / complete_task. |
| archive_task | Soft-delete a task by archiving it. Requires a reason. Destructive. |
| create_project | Create a project in the workspace. Keys scoped to specific projects cannot create one. |
| create_epic | Create an epic to group related tasks. |
| link_tasks | Declare relationships: blocks, relates_to, duplicate_of. |
| add_comment | Comment on a task: questions, findings, context for the reviewer. |
Company knowledge
| search | OpenAI-shaped search over workspace tasks. Returns id, title, and a citation URL. |
|---|---|
| fetch | OpenAI-shaped fetch of one task by UUID or identifier. Body is description plus criteria, not activity. |
Guardrails, summarized: one workspace per connection · authoring lands in Triage under the default supervised policy · every action is attributed to the agent’s identity on the activity feed · access is revocable from Masaro at any time.