This server provides AI assistants with the ability to manage Jira issues and projects via the Jira Cloud REST API v3. Capabilities include:
Create issues (jira_create_issue): Create tickets with custom fields and automatic plain-text to ADF conversion.
Read issues (jira_get_issue): Fetch full issue details by ID or key.
Search issues (jira_search_jql): Query issues using JQL with configurable limits.
Transition issues: Use jira_get_transitions to list available workflow transitions and jira_transition_issue to apply them.
Discover metadata: Use jira_get_create_metadata and jira_get_create_issue_meta_fields to inspect project/issue type fields, custom fields, and allowed values before creation.
List issue types (jira_get_project_issue_types): Get all issue types and IDs for a project.
Find users (jira_find_users): Search for users to resolve account IDs for assignments.
Authentication supports Jira Cloud (Basic Auth) and Jira Data Center (PAT) via environment variables.
Provides tools for interacting with Jira Cloud, enabling issue creation (with automatic Atlassian Document Format conversion), retrieval, JQL searching, transition management, user search, and project metadata inspection.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Jira Cloud MCP Server Create an issue in the Mobile App project: 'Push notifications not working'."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A production-ready, clean, and modular Model Context Protocol (MCP) server that enables LLMs to communicate directly with the official Jira Cloud REST API v3 using standard STDIO transport. Built using TypeScript strict mode and axios.
jira_get_create_metadata: Inspect projects, issue types, field requirements, and custom field IDs (customfield_XXXXX).
jira_get_create_issue_meta_fields: Fetch the field configurations and custom fields for a specific project and issue type when creating an issue (granular and high-performance alternative).
jira_get_project_issue_types: Fetch all issue types available for a specific project, including their IDs (used to retrieve metadata fields).
jira_create_issue: Create new tickets, automatically converting plain text descriptions into the required Jira Cloud Atlassian Document Format (ADF). Supports optional custom fields.
jira_get_issue: Fetch complete details for a ticket using its ID or Key.
jira_search_jql: Query issues using Jira Query Language (JQL) with customizable limits.
jira_find_users: Search for Jira users to retrieve their unique accountId (required for assigning issues or setting user fields in Jira v3).
jira_get_transitions: Retrieve the workflow transitions and statuses available for a specific issue, along with their transitionIds.
jira_transition_issue: Transition an issue to a new status (e.g., "Done", "QA") using a transition ID.
Related MCP server: Jira MCP Server
The server supports both Jira Data Center (PAT Bearer Token) and Jira Cloud (Basic Auth).
Define these environment variables:
Environment Variable | Description | Example |
| The root URL of your Jira Data Center instance |
|
| Your Personal Access Token (PAT) |
|
To create a PAT in Jira Data Center, navigate toProfile > Personal Access Tokens and click Create token. Keep JIRA_EMAIL undefined (or do not set it) to trigger Bearer Token authentication.
Define these environment variables:
Environment Variable | Description | Example |
| The root URL of your Jira Cloud instance |
|
| The email associated with your Atlassian account |
|
| Atlassian API Token |
|
npm installCreate a .env file in the root directory for local testing:
Jira Data Center (PAT):
JIRA_HOST=https://jira.yourcompany.com
JIRA_API_TOKEN=your-personal-access-token
# Leave JIRA_EMAIL blank or omit itJira Cloud (Basic):
JIRA_HOST=https://your-domain.atlassian.net
JIRA_EMAIL=user@company.com
JIRA_API_TOKEN=your-api-tokenCompiles the TypeScript source files into executable ESM JavaScript in the dist/ directory:
npm run buildOnce built or published, the server can be executed directly using Node.js:
# Run the local build
node bin/index.jsOr run via npx (if published or linked):
npx jira-mcp-serverTo connect this MCP server to a client (e.g., Claude Desktop, Cursor, or Antigravity), use the following configuration layouts.
Add the configuration snippet below to your Claude Desktop config file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"jira-mcp-server": {
"command": "node",
"args": [
"/absolute/path/to/jira-mcp/bin/index.js"
],
"env": {
"JIRA_HOST": "https://your-domain.atlassian.net",
"JIRA_EMAIL": "user@company.com",
"JIRA_API_TOKEN": "your-api-token"
}
}
}
}Configure a command-based MCP server in your IDE:
Type: command
Command: node /absolute/path/to/jira-mcp/bin/index.js
Set the environment variables JIRA_HOST, JIRA_EMAIL, and JIRA_API_TOKEN in your system or project configuration.
To distribute this package inside your organization using JFrog Artifactory as your private NPM registry:
Add a publishConfig object to your package.json to redirect publishing to Artifactory:
"publishConfig": {
"registry": "https://<your-jfrog-domain>/artifactory/api/npm/<npm-repository-name>/"
}Alternatively, create a .npmrc file in the root of the project:
registry=https://<your-jfrog-domain>/artifactory/api/npm/<npm-repository-name>/Log in to your private registry using your corporate credentials:
npm login --registry=https://<your-jfrog-domain>/artifactory/api/npm/<npm-repository-name>/Compile the TypeScript code and upload the package:
npm run build
npm publishnpxTo run the server dynamically using npx from your private JFrog repository, specify the registry parameter:
npx --registry=https://<your-jfrog-domain>/artifactory/api/npm/<npm-repository-name>/ jira-mcp-server(Optional) If you set your global npm registry configuration to point to your Artifactory NPM proxy (which resolves both local and public NPM packages):
npm config set registry https://<your-jfrog-domain>/artifactory/api/npm/<npm-repository-name>/
npx jira-mcp-serverCreates a new issue, task, bug, or custom asset issue in Jira Cloud. Note: Description must be in Atlassian Document Format (ADF) - if you provide a plain string, this tool will automatically wrap it into a valid ADF paragraph node for you. IMPORTANT: If you need to populate custom fields or do not know what fields are required for the project, you MUST first run jira_get_project_issue_types to get the issueTypeId, and then run jira_get_create_issue_meta_fields to inspect the available fields, retrieve their exact "customfield_XXXXX" keys, and check their required states and allowed values. Then pass them in the "customFields" parameter. Official API Doc Link: https://developer.atlassian.net/cloud/jira/platform/rest/v3/api-group-issues/#api-rest-api-3-issue-post
| Name | Required | Description | Default |
|---|---|---|---|
| summary | Yes | A brief summary/title of the issue. | |
| projectKey | Yes | The key of the project to create the issue in (e.g., "PROJ"). | |
| description | No | The description of the issue. Can be a plain string (which will be auto-converted to ADF) or a full Atlassian Document Format (ADF) object. | |
| customFields | No | Optional custom fields key-value pairs (e.g., {"customfield_10010": "Value", "customfield_10011": 12.5}). These must be discovered first by calling `jira_get_create_issue_meta_fields` to get their correct customfield_XXXXX IDs and expected types. | |
| issueTypeName | Yes | The name of the issue type (e.g., "Task", "Bug", "Story", "Epic"). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description carries the full burden of behavioral disclosure. It effectively discloses that the description parameter requires ADF and will be auto-wrapped if provided as a plain string, and that customFields need exact customfield_XXXXX IDs from the metadata tool. However, it does not mention the response structure or error behavior, which is a minor gap for a create operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a main sentence, a note about ADF format, and an IMPORTANT workflow callout. It contains no filler, and every sentence provides essential guidance. While somewhat lengthy due to the IMPORTANT section, the complexity of the tool justifies the length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description does not explain what the tool returns, which is a notable omission. However, it thoroughly covers the critical input workflow from metadata discovery to ADF formatting, which is the most complex aspect of using this tool. The description is highly functional for a create operation, but could be complete with a note about the response (e.g., issue key).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents all 5 parameters with descriptions, achieving 100% coverage. The description adds meaningful context beyond the schema: it explains the ADF auto-wrapping behavior for the description parameter and emphasizes that customFields must be discovered first via jira_get_create_issue_meta_fields, which enriches the semantic understanding of these parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool creates a new issue, task, bug, or custom asset issue in Jira Cloud, using the verb 'Creates' and a specific resource. It distinguishes itself from sibling tools like jira_get_issue, jira_search_jql, and jira_get_transitions, which all perform read or transition operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs that if custom fields are needed or unknown, the agent MUST first run jira_get_project_issue_types and jira_get_create_issue_meta_fields to discover the correct field IDs and required states. This provides a clear workflow and names the alternative tools to use, with an official API doc link for further reference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Searches for Jira users by display name, username, or email address. IMPORTANT: Because Jira Cloud v3 requires the user's accountId (e.g. '5b10ac8d82e05b22cc7d4ef5') for assignees, reporters, and user fields instead of usernames or emails, you MUST run this tool first to resolve a user's display name or email to their unique accountId. Official API Doc Link: https://developer.atlassian.net/cloud/jira/platform/rest/v3/api-group-user-search/#api-rest-api-3-user-search-get
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | The search query string (e.g. displayName, nickname, or email address). | |
| maxResults | No | The maximum number of items to return (default is 50, maximum is 100). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses a key behavioral nuance: Jira Cloud v3 requires accountId instead of usernames/emails, and this tool performs the resolution. It does not detail the exact response structure or pagination, but the essential behavior is well communicated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences, front-loaded with the purpose and immediately followed by the important usage note. The included API doc link is a useful addition without bloating the text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description effectively positions the tool as a prerequisite step within the Jira workflow, explains why it is necessary, and provides an API reference. Given the simple schema and clear output implication (resolving to accountId), it is contextually complete even without an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides complete descriptions for both parameters (query and maxResults), covering 100% of parameter semantics. The description adds context about accountId but does not significantly extend parameter-level meaning beyond what the schema offers.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches for Jira users by display name, username, or email address. This is a specific verb and resource, and it is distinct from sibling tools that focus on issues and metadata, making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs that this tool MUST be run first to resolve a user's display name or email to their accountId before using assignee/reporter fields in Jira Cloud v3. This provides clear when-to-use guidance and ties directly into the workflow of sibling tools like jira_create_issue.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetches the field configurations and custom fields for a specific project and issue type when creating an issue. Run this to discover the exact customfield_XXXXX IDs, their expected data types (e.g. string, number, array), and whether they are required before invoking jira_create_issue. This is a highly performant and granular alternative to the deprecated global getCreateMetadata endpoint. Official API Doc Link: https://developer.atlassian.net/cloud/jira/platform/rest/v3/api-group-issues/#api-rest-api-3-issue-createmeta-projectidorkey-issuetypes-issuetypeid-get
| Name | Required | Description | Default |
|---|---|---|---|
| startAt | No | The index of the first item to return in a page of results (default is 0). | |
| maxResults | No | The maximum number of items to return per page (default is 50, maximum is 50). | |
| issueTypeId | Yes | The ID of the issue type (e.g., "10001"). These must be retrieved first by calling `jira_get_project_issue_types`. | |
| projectIdOrKey | Yes | The project ID or key (e.g., "10000" or "PROJ"). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that the tool returns customfield IDs, data types, and required flags, and claims high performance. It does not mention error behavior, rate limits, or pagination details, but for a read-only metadata fetch, the description gives reasonable transparency about what the user will discover.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with a supporting API link. The first sentence states purpose, the second gives usage guidance and distinguishes from an alternative. No fluff; every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a metadata fetch tool with no output schema, the description explains the key output (field IDs, types, required) and the workflow context (before create). It lacks details on startAt/maxResults behavior, but those are covered in the schema. The API reference link adds completeness. Could mention error cases, but overall comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with all parameters described. The description does not add extra parameter-specific meaning beyond the schema, but it reinforces the purpose of the output (customfield IDs and types), which indirectly ties to the parameters. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches field configurations and custom fields for a specific project and issue type during creation. It distinguishes itself from siblings by emphasizing granularity for a specific project/issue type and explicitly naming the deprecated global getCreateMetadata endpoint as an alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly directs the user to run it 'before invoking `jira_create_issue`' to discover required fields and types. It also tells the user this is a 'highly performant and granular alternative' to the deprecated global endpoint, providing clear guidance on when to use this tool instead of that one.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetches creation metadata and field configurations for a specific project and issue type, including custom fields (customfield_XXXXX), required states, and allowed option values. Required to know which fields are expected and what their types are before creating an issue. Official API Doc Link: https://developer.atlassian.net/cloud/jira/platform/rest/v3/api-group-issue-creation-metadata/#api-rest-api-3-issue-createmeta-get
| Name | Required | Description | Default |
|---|---|---|---|
| projectKeys | No | Comma-separated list of project keys (e.g., "PROJ,TEST"). | |
| issueTypeNames | No | Comma-separated list of issue type names (e.g., "Bug,Task,Story"). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits itself. It indicates a read-only fetch and describes the output contents, but it does not mention what happens when the optional parameters are omitted, potential error conditions, or authentication needs. This leaves notable gaps in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences plus an API link, front-loading the core purpose efficiently. The second sentence provides usage context but is somewhat redundant with the first, so it is concise without being maximally tight.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description should compensate by detailing the response structure. It offers a high-level overview but does not explain behavior when both parameters are omitted or clarify differences from a similarly named sibling. The API doc link helps but does not fully close the gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already achieves 100% coverage, clearly describing both parameters as comma-separated lists. The description adds no additional parameter-level meaning, so it stays at the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'fetches creation metadata and field configurations' with specific details about custom fields, required states, and allowed values. However, it does not distinguish this tool from the similarly named sibling jira_get_create_issue_meta_fields, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says it is 'required before creating an issue,' which gives clear context for when to use the tool. But it offers no exclusions or alternatives, such as when to prefer the sibling jira_get_create_issue_meta_fields, making the guidance only partially explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves comprehensive details for a specific Jira issue or asset by its ID or Key (e.g., "PROJ-123" or "10001"). Official API Doc Link: https://developer.atlassian.net/cloud/jira/platform/rest/v3/api-group-issues/#api-rest-api-3-issue-issueidorkey-get
| Name | Required | Description | Default |
|---|---|---|---|
| issueIdOrKey | Yes | The ID or Key of the issue to retrieve (e.g., "PROJ-123" or "10001"). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden for behavioral disclosure. The verb 'retrieves' indicates a read operation, and 'comprehensive details' gives some expectation of output, but the description does not mention authorization requirements, error behavior for nonexistent issues, or what specific fields are included. The API doc link offers additional context, but the description itself lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that immediately conveys the tool's purpose and includes a concrete example. The official API doc link is a useful additional resource without cluttering the text. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (one required parameter), and the description provides the essential purpose and an example. The API doc link supplements missing details about return values and error cases. For a straightforward retrieval tool, this is near-complete, though lacking explicit handling of invalid IDs or permissions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description repeats the parameter semantics already present in the schema ('ID or Key' and examples) without adding additional meaning, such as format constraints or behavior with different input types. The value is equivalent to the schema's own description, so no extra credit is warranted.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool retrieves a specific Jira issue or asset by ID or Key, with examples ('PROJ-123' or '10001'). This specific verb+resource combination distinguishes it from sibling tools like jira_search_jql, which searches across issues, and jira_create_issue, which creates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the appropriate use case (when you have an issue ID or Key and need comprehensive details) but does not explicitly contrast it with alternatives. It does not mention when to use jira_search_jql instead, or state that this tool is for single-issue retrieval. The API doc link partially compensates, but explicit exclusion guidance is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetches the issue types available within a specific project, including their IDs. You MUST use this tool first to resolve the issueTypeId needed for calling jira_get_create_issue_meta_fields (which discovers required custom fields for a specific project/issue type). Official API Doc Link: https://developer.atlassian.net/cloud/jira/platform/rest/v3/api-group-issues/#api-rest-api-3-issue-createmeta-projectidorkey-issuetypes-get
| Name | Required | Description | Default |
|---|---|---|---|
| startAt | No | The index of the first item to return in a page of results (default is 0). | |
| maxResults | No | The maximum number of items to return per page (default is 50, maximum is 50). | |
| projectIdOrKey | Yes | The project ID or key (e.g., "10000" or "PROJ"). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry behavioral context. It does convey that this is a read operation ('Fetches') and that it returns issue IDs. However, it doesn't disclose error behavior, pagination limits beyond schema, or any side effects, leaving some ambiguity for an agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences plus a documentation link. The first sentence captures the core function, the second provides essential usage context, and the link offers deep reference. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a relatively simple fetch tool with no output schema, the description covers the primary purpose, the prerequisite relationship to another tool, and provides the official API reference. It doesn't elaborate on return structure or error cases, but given the tool's simplicity and schema coverage, it's sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema provides descriptions for all three parameters (projectIdOrKey, startAt, maxResults) with 100% coverage. The description doesn't add any additional meaning about parameter values or relationships beyond what's in the schema, so it stays at baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Fetches the issue types available within a specific project, including their IDs.' This is a specific verb+resource and explicitly distinguishes from sibling `jira_get_create_issue_meta_fields` by positioning this tool as the prerequisite for resolving issueTypeId.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit guidance: 'You MUST use this tool first to resolve the issueTypeId needed for calling jira_get_create_issue_meta_fields.' This establishes a clear when-to-use scenario. It doesn't name alternative tools or exclusions, but the sequence is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves the list of transitions (status changes) available for a specific Jira issue. This is crucial for discovering what workflow stages (e.g. 'In Progress', 'Done', 'Blocked') the issue can currently move to, and obtaining the correct transitionId (e.g. '31') to transition it. Official API Doc Link: https://developer.atlassian.net/cloud/jira/platform/rest/v3/api-group-issues/#api-rest-api-3-issue-issueidorkey-transitions-get
| Name | Required | Description | Default |
|---|---|---|---|
| issueIdOrKey | Yes | The ID or Key of the issue (e.g. "PROJ-123" or "10000"). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of disclosing behavior. The verb 'Retrieves' clearly indicates a read-only operation, and the description goes further by explaining what data is returned (transitions and transitionId) and giving examples. It does not explicitly state 'does not modify the issue,' but the phrasing is unambiguous enough for a safe read tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences of high-value content plus an official API link. It starts with the verb and resource, then explains the practical use, all without unnecessary words. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one parameter and no output schema, but the description explains the purpose, the nature of the returned data (list of transitions with transitionIds), and why it is needed (to transition an issue). It also provides an official API link for deeper details, making it complete for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a clear description for the single parameter 'issueIdOrKey'. The description only references 'a specific Jira issue' without adding new semantics beyond the schema. Since the schema fully explains the parameter, the description adds no significant extra meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Retrieves' with a specific resource: 'the list of transitions (status changes) available for a specific Jira issue.' It clearly distinguishes itself from the sibling tool 'jira_transition_issue' by focusing on reading available transitions rather than performing the transition.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states 'This is crucial for discovering what workflow stages... and obtaining the correct transitionId... to transition it,' which clearly implies when to use this tool (before transitioning an issue). It doesn't explicitly name 'jira_transition_issue' as the alternative, but the use case and sibling list make it unmistakable. However, it lacks explicit 'do not use when' guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Searches for Jira issues/assets using Jira Query Language (JQL). Official API Doc Link: https://developer.atlassian.net/cloud/jira/platform/rest/v3/api-group-issue-search/#api-rest-api-3-search-get
| Name | Required | Description | Default |
|---|---|---|---|
| jql | Yes | The JQL query string (e.g., "project = PROJ AND status = \"To Do\" ORDER BY created DESC"). | |
| maxResults | No | The maximum number of items to return (default is 50, maximum is 100). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility for disclosing behavioral traits. It only states the basic action and does not mention read-only nature, authentication requirements, pagination, or any side effects. The API doc link is external but not part of the actionable description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that states the purpose clearly, with no unnecessary words. The official API doc link is a useful addition and does not detract from conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema and no annotations. The description fails to provide any context about return format, pagination behavior, error conditions, or prerequisites. While the parameters are fully described in the schema, overall completeness is lacking for an agent to confidently invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for both parameters, so the baseline is 3. The description does not add any extra parameter semantics beyond what the input schema already provides, such as examples or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Searches') and names the resource ('Jira issues/assets') and the query language (JQL). It clearly distinguishes this tool from siblings like jira_get_issue and jira_create_issue, which perform different actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies usage: use when you need to search issues/assets via JQL. It provides clear context about the tool's role among the sibling tools, though it does not explicitly mention when not to use it or name alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Transitions a Jira issue to a different workflow status (e.g. 'In Progress', 'Done', 'Blocked') using a specific transition ID. IMPORTANT: You must first retrieve the valid transition ID by calling jira_get_transitions for this specific issue. Official API Doc Link: https://developer.atlassian.net/cloud/jira/platform/rest/v3/api-group-issues/#api-rest-api-3-issue-issueidorkey-transitions-post
| Name | Required | Description | Default |
|---|---|---|---|
| fields | No | Optional fields to set or update during the transition (e.g., {"resolution": {"name": "Fixed"}} or other custom fields). | |
| issueIdOrKey | Yes | The ID or Key of the issue (e.g. "PROJ-123" or "10000"). | |
| transitionId | Yes | The ID of the transition to trigger (e.g. "31"). This must be obtained by running `jira_get_transitions` first. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It states that a transition ID is required and references the official API, but does not mention permissions, side effects, or failure handling. The explicit call to jira_get_transitions adds useful context, but the mutating nature is only implied by the word 'Transitions'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences plus a reference link, with no unnecessary padding. It front-loads the action, provides examples, and places the critical prerequisite prominently with 'IMPORTANT'.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (3 parameters, nested objects, no output schema) and zero annotations, the description covers the key workflow step (fetching transition IDs) and the purpose. However, it does not describe return values or what a successful transition does beyond the status change, leaving a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of parameters with clear descriptions, so the baseline is 3. The tool description adds no further parameter-level meaning beyond the schema; the example in the schema for 'fields' is also present. Thus the description does not need to compensate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Transitions') and resource ('Jira issue') and gives concrete examples of statuses ('In Progress', 'Done', 'Blocked'). It clearly differentiates from sibling tools like jira_create_issue or jira_get_issue by focusing on workflow status changes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on a key prerequisite: 'IMPORTANT: You must first retrieve the valid transition ID by calling jira_get_transitions for this specific issue.' This tells the agent when and how to use the tool, though it does not mention alternative tools or exclusions, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0jira_create_issuejira_find_usersjira_get_create_issue_meta_fieldsjira_get_create_metadatajira_get_issuejira_get_project_issue_typesjira_get_transitionsjira_search_jqljira_transition_issueScored across 9 tools
Most tools have clearly distinct purposes (create, get, search, transition, find users), but jira_get_create_metadata and jira_get_create_issue_meta_fields overlap heavily—both retrieve field configuration for issue creation. This minor redundancy creates slight ambiguity, though the descriptions and the create_issue tool's guidance help steer agents to the preferred metadata tool.
All tools consistently follow the jira_<verb>_<noun> pattern using snake_case. Even longer compound names like jira_get_create_issue_meta_fields and jira_get_project_issue_types maintain a predictable and ordered structure. No mixing of conventions or style conflicts.
Nine tools is a well-scoped set for a Jira Cloud server, covering issue creation, retrieval, search, transitions, user lookup, and metadata exploration. The count feels appropriate—neither too sparse nor overburdened—and each tool (except the metadata duplication) earns its place.
The server covers issue creation, retrieval, search, and workflow transitions, but lacks general issue update and delete operations. Without jira_update_issue or jira_delete_issue, agents cannot modify existing issues (e.g., change assignee, priority, or labels) or remove issues, which is a notable gap for full lifecycle management.
Connect to Atlassian Jira, Confluence, Loom, and more to search, create, and manage your work.
Task management for people and AI agents, with scoped OAuth access to issues, projects, and docs.
Task manager your agent can fully operate: boards, tasks, sprints, roles, worklogs, day planner.
Provides cloud browser automation capabilities using Stagehand and Browserbase, enabling LLMs to i…