list_epics
A project's epics in the project's order, with reference, goal, owner, priority, status and dates, narrowed for a guest token.
Return the epics of one project, the bodies of work it will deliver, each with its reference (such as CRM-12), title, goal, the prose (summary, business value, hypothesis, success metrics), owner, MoSCoW priority, status, dates and colour. Read it before you write, estimate or implement a story, so the work hangs under the right epic and the goal is in front of you, and name epics by their reference when you report.
Optional filters narrow the page to one status, one priority, one owner_id or the epics whose reference, title or goal contain search. A guest token reads the agreed epics only (approved, in progress or done).
Requires ability
The token behind the MCP session must hold it, or the call is refused with TOKEN_MISSING_ABILITY.
Runs the same action as
The REST endpoint and this tool share one action, so validation, permissions and events are identical.
Annotations
It reads and never changes anything.
Arguments
project_id*stringUUID of the project whose epics to list.
statusstringoptionalNarrow to one status.
draftin_reviewapprovedin_progressdonecancelledprioritystringoptionalNarrow to one MoSCoW priority.
mustshouldcouldwontowner_idstringoptionalNarrow to the epics one person answers for, by user UUID.
searchstringoptionalWords the reference, the title or the goal must contain.
limitintegeroptionalEpics per page (1..100, default 25).
1max100pageintegeroptional1-indexed page number.
1What it returns
{ "data": [ { "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d", "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13", "number": 12, "reference": "CRM-12", "title": "Loyalty tiers", "summary": "<p>Members climb silver, gold and platinum tiers by annual spend.</p>", "goal": "Reward the top fifth of members so they keep buying from the client.", "business_value": null, "hypothesis": "A visible next tier raises repeat purchases within a quarter.", "success_metrics": null, "owner_id": "c3d4e5f6-a7b8-4c9d-8e0f-1a2b3c4d5e6f", "owner_name": "Nimal Fernando", "priority": "must", "status": "approved", "starts_on": "2026-11-02", "due_on": "2027-03-31", "color": "amber", "position": 0, "version": 0, "approved_at": "2026-11-05T15:00:00+00:00", "approved_revision_id": null, "created_at": "2026-10-28T09:20:00+00:00", "updated_at": "2026-11-05T15:00:00+00:00" } ], "meta": { "page": 1, "limit": 25, "total": 1, "has_more": false }}How it fails
RESOURCE_NOT_FOUNDunknown project_id, or a project outside the token's scope or the person's visibility.
VALIDATION_FAILEDstatus or priority is not one of its values.
TOKEN_MISSING_ABILITYtoken lacks epic:view-any.
How is this guide?
Last updated on