create_issue — MCP tool

added 2026-09-28

Create an epic, story or task. Stories go under an epic, tasks under a story, via parent.

assigneestringoptional
Assignee username
confirm_open_criteriaboolean | string[]optional
Confirm the open items of your own criteria when the new issue is created in a done status and the project's done_gate is warn: send true (any caller, agents too: the items are your own text of this request, they have no ids yet). Under done_gate block nothing confirms it.
criteriaobject[]optional
Your own AC / DoD items for the new issue, after the template ones: [{kind: ac|dod, text}] (a list the project has off is refused)
cyclestringoptional
current, next or a cycle number
descriptionstringoptional
Markdown description; @username mentions are resolved; ![title](https://sysdraw.app/s/<token>) = sysdraw view link; a ```mermaid block is drawn as a diagram
description_templateenumoptional
Optional built-in skeleton, used as the description only when description is empty: bug (Summary, Steps to reproduce, Expected behavior, Actual behavior, Environment), feature (Problem, Proposal, Alternatives considered, Out of scope), research (Question, Context, Approach, Findings, Recommendation). bug and feature also add the project's label of that name when it exists and labels is absent or null. A description you give wins (not an error)
bugfeatureresearch
due_datestringoptional
Due date, YYYY-MM-DD (optional)
idempotency_keystringoptional
Optional, 1–128 visible ASCII characters (a UUIDv4 is fine). The same key and arguments within 24 h return the original result and create nothing; the same key with different arguments is rejected. The key is scoped to you and to this tool, and shared with the HTTP Idempotency-Key header.
labelsstring[]optional
Label names (must exist); [] means none (no template label); null or absent lets the template add its label
parentstringoptional
Parent issue key
priorityenumoptional
Priority
nonelowmediumhighurgent
projectstringrequired
Project key
skip_criteriaenum | string[]optional
Templates NOT to copy onto the new issue: "none" (no templates at all) or an array of template ids (list_criteria_templates). Default: every template that matches the type and parent. An issue created in a done status gets none
none
statusstringoptional
Initial status: a key or name from list_statuses (default: the project's first to-do status)
titlestringrequired
Short summary
typeenumoptional
Issue type (default task)
epicstorytask

Returns

criteriaobjectoptional
Counts of the AC / DoD items the new issue got (only for a kind the project has on)
deletedbooleanoptional
Replay only: the issue created by the first call has since been deleted
idstring (uuid)required
keystringrequired
replayedbooleanoptional
True when the idempotency_key had been used before: nothing was created
statusstringrequired
Status key
status_namestringrequired
titlestringrequired
typestringrequired
urlstringoptional

2026-10-05 — New optional cycle argument: current, next or a cycle number (list_cycles); "" takes the issue out of its cycle (update only).
2026-10-01 — New optional due_date argument (YYYY-MM-DD).
2026-10-03 — New optional idempotency_key argument: a retry with the same key and arguments within 24 h returns the original answer and creates nothing.
2026-10-05 — New optional description_template argument (bug, feature, research): its section skeleton becomes the description when none is given (a given description wins and the answer says the skeleton was not used); bug and feature also add the project's label of the same name when it exists and labels is absent or null (labels: [] adds none). Type, priority, status, parent and criteria are never touched.
2026-10-06 — A sysdraw diagram can be embedded in a description or comment: write its view link as an image line, ![title](https://sysdraw.app/s/<22-character token>) (a bare link stays a link); get_issue_details shows it the same way. Only view links anyone can open are accepted; a comment, edit or signed-in-only link is refused with the reason, and a new diagram is saved only after sysdraw confirmed it (a person can add about 60 new links per 15 minutes; when sysdraw cannot be asked the call fails and can be retried). Diagrams already in the text are not checked again.
2026-10-09 — A Mermaid diagram can be written in a description or comment as a fenced code block: ```mermaid, the diagram source, ```. The web app draws it as a diagram (with a Show source toggle); the source stays in the text and get_issue_details gives it back unchanged. Not drawn (the source is shown instead): config directives (%%{init: ...}%% lines), front matter (a leading --- block), image shapes (img:), and diagrams over about 20 000 characters or 500 lines; one over about 8 000 characters or 150 lines (a mindmap: 80 lines) is drawn when the reader presses Draw.
2026-10-03 — New optional skip_criteria ("none" or template ids), criteria [{kind: ac|dod, text}] and confirm_open_criteria (true) for a create in a done status with open items of your own. The answer says how many items the issue got.
2026-10-03 — Also answers structuredContent (see outputSchema); a failed call adds structuredContent.error. Text unchanged. Details: /docs/mcp, "Structured results and errors".
2026-10-04 — Claude Code 2.1.288+ (clientInfo claude-code): the text of a successful answer is itself up to 512 bytes, else "Result in structuredContent (N bytes)."; structuredContent and errors are unchanged. See /docs/mcp.