Project workspace
Tools that read and act on work items, sprints, workflow statuses and comments inside the project workspace module.
The Project workspace tools mirror the backlog, active sprint, and work item detail experiences inside plnnrly. They let an AI client look up a work item by its issue key (e.g. ACM-123), browse and filter backlogs and sprints, create and update work items, move them through workflow statuses, manage sprint lifecycles, and read or add comments to a work item's timeline.
Every call runs as the user who minted the MCP token. Tenant isolation is enforced by the server, and per-tool authorization checks the user's plnnrly permissions before anything is read or written.
Tools
| Tool | Purpose |
|---|---|
get-work-item-by-key-tool | Look up a single work item by its issue key (e.g. ACM-123). |
get-work-item-attachments-tool | List a work item's file attachments with short-lived download URLs. |
list-work-items-tool | List work items in a project, optionally scoped to a sprint, with rich filters. |
list-sprints-tool | List sprints in a project, optionally filtered by state. |
list-workflow-statuses-tool | List the workflow statuses available on a project, with their allowed transitions. |
list-work-item-comments-tool | Read the comment thread on a work item. |
add-comment-to-work-item-tool | Append a comment to a work item, authored as the calling user. |
create-work-item-tool | Create a new work item; the issue key is generated automatically. |
update-work-item-tool | Update any subset of writable fields on a work item in one call. |
transition-work-item-status-tool | Move a work item to a different workflow status, validated against the project workflow. |
create-sprint-tool | Create a sprint in the upcoming state. |
start-sprint-tool | Activate a sprint; rejects when another sprint is already active on the project. |
complete-sprint-tool | Complete the active sprint with a chosen strategy for unresolved work items. |
Permissions at a glance
| Action | Permission |
|---|---|
| Read backlog / sprint / work item / comments | project_management::view_backlog |
| Read the active sprint only | project_management::view_active_sprint |
| Create, update, transition work items; add comments | project_management::manage_work_items |
| Create, start, complete sprints | project_management::manage_sprints |
Authorization is layered: route-level token ability + tenant identification, then a per-tool permission check, then a model-policy authorization on the target record (write tools only), then domain-rule enforcement (e.g. workflow transitions, single-active-sprint). Missing permissions cause the tool to return an authorization error.
Common workflows
- "What's the description on ACM-123?" —
get-work-item-by-key-tool. - "Add a comment to ACM-123 saying it's blocked on legal." —
add-comment-to-work-item-tool. - "Create a 'Stripe SDK upgrade' task in the Website project." —
create-work-item-tool. - "Move ACM-42 to In Progress." —
transition-work-item-status-tool(first calllist-workflow-statuses-toolto find the target status id). - "Start a new sprint and move it from upcoming to active." —
create-sprint-toolthenstart-sprint-tool. - "Complete this sprint and move unresolved items to the next one." —
complete-sprint-toolwithunresolved_work_items: "move_to_next_sprint".