search_issues | jira:issues:read | Search Jira issues using JQL (Jira Query Language). Returns {issues, nextPageToken, isLast} — pass nextPageToken back to fetch the next page (the legacy startAt/total response shape was retired by Atlassian on 2025-05-01). |
get_issue | jira:issues:read | Get a single Jira issue by its key (e.g. ACME-123). STRONGLY recommend passing fields — Atlassian's default response includes 100+ custom-field entries (most null) and runs ~10 KB per issue. A typical agent request only needs a handful: try "summary,status,priority,assignee,reporter,description,issuetype,labels,created,updated". Description bodies come back as ADF (Atlassian Document Format) JSON, not plain text. |
get_transitions | jira:issues:read | List the workflow transitions currently available on a Jira issue. Each entry carries an id (string) you pass to transition_issue. Transition IDs and labels vary per project workflow — "Done" might be "31" in one project, "41" or "61" in another — so always discover via this tool before calling transition_issue instead of guessing. |
list_comments | jira:issues:read | List the comments on a Jira issue. Returns {comments, startAt, maxResults, total} — each comment carries its id, author, created/updated, and an ADF body. Pass startAt to page. |
list_worklogs | jira:issues:read | List the worklogs (time entries) on a Jira issue. Returns {worklogs, startAt, maxResults, total} — each worklog carries its id, author, timeSpentSeconds, started, and an ADF comment. Read a worklog's id here before update_worklog / delete_worklog. |
create_issue | jira:issues:write | Create a new Jira issue. IMPORTANT: Atlassian Cloud's REST API v3 requires the description field (if present) to be an Atlassian Document Format (ADF) JSON object, NOT a plain string — passing plain text returns HTTP 400 with no useful error. If you don't need a description, omit it entirely (the example below shows the minimal valid shape). If you DO need one, wrap your text in ADF as shown in the second example. |
add_comment | jira:issues:write | Add a comment to a Jira issue. The body must be an ADF (Atlassian Document Format) doc, NOT a plain string — same caveat as create_issue. Shape: {"issue_key": "ACME-123", "body": {"type": "doc", "version": 1, "content": [{"type": "paragraph", "content": [{"type": "text", "text": "On it."}]}]}}. |
update_issue | jira:issues:write | Update an existing Jira issue. Two payloads, either or both: fields assigns values, update runs verb-style operations (add/edit/remove) for the things fields cannot express — worklogs above all, since timeSpent is derived from worklogs and is read-only as a field. Log time with update, not fields. Same ADF caveat as create_issue: any description you pass must be an ADF doc, not a plain string, or Atlassian returns HTTP 400. |
update_comment | jira:issues:write | Edit an existing comment on a Jira issue, overwriting its body. Get the comment_id from list_comments. The body must be an ADF doc (same caveat as add_comment). Shape: {"issue_key": "ACME-123", "comment_id": "10042", "body": {"type": "doc", "version": 1, "content": [...]}}. |
add_worklog | jira:issues:write | Log time against a Jira issue. This is the endpoint to use for time tracking: it returns the created worklog (with its id), so the caller can prove the time landed. update_issue's update verb also carries worklog ops, but answers 204 with no body — a worklog the project silently discards is indistinguishable there from one it stored. Note that time tracking must be enabled on the project; if it is not, Jira accepts the call and records nothing. |
add_attachment | jira:issues:write | Attach a file to a Jira issue. Because MCP arguments are JSON, the file is supplied as base64 in file_content_base64 (plus a filename); the gateway assembles the multipart/form-data upload and adds Atlassian's required X-Atlassian-Token header. Returns an array with the created attachment's id and metadata. |
update_worklog | jira:issues:write | Edit an existing worklog on a Jira issue, overwriting its time/comment. Get the worklog_id from list_worklogs. Same started format caveat as add_worklog (milliseconds + colon-less offset). Send timeSpentSeconds or timeSpent, not both. |
transition_issue | jira:issues:write | Transition a Jira issue through a workflow (e.g. Open → In Progress → Done). Discover valid transition IDs first via get_transitions — IDs are workflow-specific and don't match across projects. |
list_link_types | jira:issues:read | List the issue link types available on this Jira site. Returns {issueLinkTypes: [{id, name, inward, outward}]} — e.g. name "Blocks" with inward "is blocked by" and outward "blocks". Call this before link_issues: type names are configured per site ("Blocks", "Relates", "Duplicate", "Cloners", and custom ones), so guessing a name returns HTTP 404. The inward/outward wording also tells you which issue goes in which slot. |
link_issues | jira:issues:write | Create a link between two Jira issues. Direction is carried by the slots, not the type name: with "Blocks", outwardIssue blocks inwardIssue — so {"type":{"name":"Blocks"},"outwardIssue":{"key":"ACME-1"},"inwardIssue":{"key":"ACME-2"}} reads "ACME-1 blocks ACME-2". Discover type names with list_link_types first; an unknown name returns HTTP 404. Succeeds with 201 and an empty body. get_issue omits links unless you pass fields="issuelinks". |
unlink_issues | jira:issues:write | Delete an issue link by its id. Get the id from get_issue with fields="issuelinks" — each entry in the returned issuelinks array carries its own id. This removes the relationship from both issues; it does not touch either issue otherwise. |
delete_issue | jira:issues:delete | Delete a Jira issue by key. This is permanent — Jira does not trash issues. By default the delete FAILS if the issue has subtasks; pass deleteSubtasks="true" to remove them too (also permanent). Gated on the dedicated jira:issues:delete scope so policy can withhold deletion without withholding writes. |
delete_comment | jira:issues:write | Delete a comment from a Jira issue by id. Permanent. Get the comment_id from list_comments. Kept on jira:issues:write (not the issues:delete scope) because it removes a single comment, not the issue. |
delete_worklog | jira:issues:write | Delete a worklog (time entry) from a Jira issue by id. Permanent, but re-loggable via add_worklog, so it is not marked always-ask. Get the worklog_id from list_worklogs. |
find_users | jira:users:read | Find Jira users by name or email. Returns an array of {accountId, displayName, emailAddress, active}. This is how you resolve the accountId that create_issue / update_issue need for assignee — Jira Cloud identifies users by opaque accountId, never username. Query with a name fragment or an email address. |
get_current_user | jira:users:read | Get the profile of the calling user (accountId, displayName, emailAddress, timeZone). Useful for 'assign to me' or filtering 'my issues' by the caller's own accountId. |
list_create_issue_types | jira:projects:read | List the issue types you can create in a project (Bug, Task, Story, Sub-task, and any custom types). Call this before create_issue so the issuetype name/id is real for THIS project — guessing a name that the project's scheme doesn't include returns HTTP 400. |
list_create_fields | jira:projects:read | List the fields available (and which are required) when creating a given issue type in a project. Use it to learn a project's mandatory custom fields before create_issue — the response's fields carries each field's key, name, required flag, and allowed values. Get the issue_type_id from list_create_issue_types. |
list_projects | jira:projects:read | List Jira projects the caller can see. Paginated — returns {values, startAt, maxResults, total, isLast}. Pass query to filter by substring (matches project name + key); pass maxResults to bound the response size (Atlassian default is 50, max 50 server-side). The legacy unpaginated /rest/api/3/project endpoint was retired in favour of this one and would overflow MCP tool-result limits at any non-trivial org size. |
get_project | jira:projects:read | Get a single Jira project by key or id (name, lead, projectTypeKey, components, issue-type scheme summary). Pass expand for extras like description, lead, issueTypes. |
list_project_statuses | jira:projects:read | List the statuses available in a project, grouped by issue type. Useful for building a JQL status = ... filter or understanding a project's workflow before transition_issue. |
list_fields | jira:projects:read | List all fields on the Jira site — system and custom. Returns each field's id (e.g. "summary", "customfield_10012"), name, and whether it is custom. This is how you map a human field name to the customfield_NNNNN id that search_issues fields and update_issue fields require. |