> ## Documentation Index
> Fetch the complete documentation index at: https://prismeai-docs-next.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Jira

> Search, create, and manage Jira issues from DSUL automations or AI agents

The Jira connector provides full access to Jira issue tracking, supporting both **Jira Cloud** and **Jira Data Center** deployments.

<CardGroup cols={3}>
  <Card title="Issue Management" icon="ticket">
    Search, create, update, and delete issues with full field support
  </Card>

  <Card title="Workflow Operations" icon="diagram-project">
    Transition issues through statuses and add comments
  </Card>

  <Card title="Project Access" icon="folder">
    List and inspect projects accessible to your account
  </Card>
</CardGroup>

## Prerequisites

* A **Jira Cloud** or **Jira Data Center** instance
* For Cloud: an **Atlassian account email** and **API token**
* For Data Center: a **Personal Access Token (PAT)**

<Note>
  Get an API token at [Atlassian API Tokens](https://id.atlassian.com/manage-profile/security/api-tokens)
</Note>

***

<Tabs>
  <Tab title="Usage as App">
    ## Installation

    1. Go to **Apps** in your workspace
    2. Search for **Jira** and install it
    3. Configure the app instance with your Jira credentials

    ## Configuration

    ### Jira Cloud

    | Field         | Value                            |
    | ------------- | -------------------------------- |
    | **Base URL**  | `https://yoursite.atlassian.net` |
    | **Type**      | `cloud`                          |
    | **Email**     | Your Atlassian account email     |
    | **API Token** | Your Atlassian API token         |

    ### Jira Data Center

    | Field                     | Value                          |
    | ------------------------- | ------------------------------ |
    | **Base URL**              | `https://jira.yourcompany.com` |
    | **Type**                  | `datacenter`                   |
    | **Personal Access Token** | Your PAT                       |

    ## Available Automations

    ### Issue Operations

    | Automation    | Description              |
    | ------------- | ------------------------ |
    | `searchJira`  | Search issues using JQL  |
    | `getIssue`    | Get issue details by key |
    | `createIssue` | Create a new issue       |
    | `updateIssue` | Update an existing issue |
    | `deleteIssue` | Delete an issue          |

    ### Workflow Operations

    | Automation        | Description                      |
    | ----------------- | -------------------------------- |
    | `getTransitions`  | Get available status transitions |
    | `transitionIssue` | Change issue status              |
    | `addComment`      | Add a comment to an issue        |
    | `addAttachment`   | Add an attachment to an issue    |

    ### Project Operations

    | Automation     | Description              |
    | -------------- | ------------------------ |
    | `listProjects` | List accessible projects |
    | `getProject`   | Get project details      |

    ## DSUL Examples

    ### Search Issues

    ```yaml theme={null}
    - Jira.searchJira:
        jql: "project = DEV AND status = 'In Progress'"
        maxResults: 10
        output: results
    ```

    ### Get Issue Details

    ```yaml theme={null}
    - Jira.getIssue:
        issueKey: DEV-123
        output: issue
    ```

    ### Create an Issue

    ```yaml theme={null}
    - Jira.createIssue:
        projectKey: DEV
        issueType: Task
        summary: Implement new feature
        description: Detailed description here
        priority: High
        output: newIssue
    ```

    ### Transition Issue Status

    ```yaml theme={null}
    - Jira.transitionIssue:
        issueKey: DEV-123
        transitionId: "31"
        comment: Moving to In Progress
        output: result
    ```

    ### Add a Comment

    ```yaml theme={null}
    - Jira.addComment:
        issueKey: DEV-123
        body: "This issue has been reviewed."
        output: comment
    ```
  </Tab>

  <Tab title="Usage as MCP">
    ## MCP Setup

    1. In the **jira-mcp** workspace, go to **Settings > Advanced** and set the **MCP Api Key** field to a strong key of your choice
    2. Open your **Knowledges project**
    3. Go to **Advanced > Tools**
    4. Click **Add** and select the **MCP** tab
    5. Enter the MCP endpoint URL
    6. In the **Headers** field, add your credentials:

    **Jira Cloud:**

    ```json theme={null}
    {
      "mcp-api-key": "your-mcp-api-key",
      "baseurl": "https://yoursite.atlassian.net",
      "email": "your-email@example.com",
      "apitoken": "your-api-token"
    }
    ```

    **Jira Data Center:**

    ```json theme={null}
    {
      "mcp-api-key": "your-mcp-api-key",
      "baseurl": "https://jira.yourcompany.com",
      "personaltoken": "your-personal-access-token"
    }
    ```

    ## Authentication Methods

    The MCP server supports **3 authentication methods** (checked in priority order):

    ### 1. HTTP Headers (per-request)

    Pass Jira credentials directly in HTTP headers alongside `mcp-api-key`. Useful for MCP clients that manage credentials externally.

    ### 2. User Session (per-user)

    Call the `configureJira` tool to store credentials in the user's platform secrets. Credentials persist across requests for that user.

    ### 3. Workspace Config (shared)

    Set credentials in workspace secrets. All users share the same Jira connection.

    |               | Jira Cloud                                             | Jira Data Center                                     |
    | ------------- | ------------------------------------------------------ | ---------------------------------------------------- |
    | **Base URL**  | `https://yoursite.atlassian.net`                       | `https://jira.yourcompany.com`                       |
    | **Auth type** | Basic Auth (email + API token)                         | Bearer token (PAT)                                   |
    | **Headers**   | `baseurl`, `email`, `apitoken`                         | `baseurl`, `personaltoken`                           |
    | **Secrets**   | `jiraBaseUrl`, `jiraType`, `jiraEmail`, `jiraApiToken` | `jiraBaseUrl`, `jiraType`, `jiraPersonalAccessToken` |

    ## Available Tools

    ### Issue Operations

    | Tool          | Description              |
    | ------------- | ------------------------ |
    | `searchJira`  | Search issues using JQL  |
    | `getIssue`    | Get issue details by key |
    | `createIssue` | Create a new issue       |
    | `updateIssue` | Update an existing issue |
    | `deleteIssue` | Delete an issue          |

    ### Workflow Operations

    | Tool              | Description                      |
    | ----------------- | -------------------------------- |
    | `getTransitions`  | Get available status transitions |
    | `transitionIssue` | Change issue status              |
    | `addComment`      | Add a comment to an issue        |
    | `addAttachment`   | Add an attachment to an issue    |

    ### Project Operations

    | Tool           | Description              |
    | -------------- | ------------------------ |
    | `listProjects` | List accessible projects |
    | `getProject`   | Get project details      |

    ### Configuration

    | Tool            | Description                         |
    | --------------- | ----------------------------------- |
    | `configureJira` | Configure Jira credentials per-user |

    ## JSON-RPC Examples

    ### Search Issues

    ```json theme={null}
    {
      "name": "searchJira",
      "arguments": {
        "jql": "project = DEV AND status = \"In Progress\"",
        "maxResults": 10
      }
    }
    ```

    ### Get Issue Details

    ```json theme={null}
    {
      "name": "getIssue",
      "arguments": {
        "issueKey": "DEV-123"
      }
    }
    ```

    ### Create an Issue

    ```json theme={null}
    {
      "name": "createIssue",
      "arguments": {
        "projectKey": "DEV",
        "issueType": "Task",
        "summary": "Implement new feature",
        "description": "Detailed description here",
        "priority": "High"
      }
    }
    ```

    ### Transition Issue Status

    ```json theme={null}
    {
      "name": "transitionIssue",
      "arguments": {
        "issueKey": "DEV-123",
        "transitionId": "31",
        "comment": "Moving to In Progress"
      }
    }
    ```

    ## Output Formats

    All tools support an `outputFormat` parameter:

    * **`verbose`** (default) - Human-readable text for LLM consumption
    * **`structured`** - Machine-readable JSON in `structuredContent`
    * **`both`** - Both text and structured content
  </Tab>
</Tabs>

***

## Error Handling

| HTTP Status | Error        | Solution                           |
| ----------- | ------------ | ---------------------------------- |
| 401         | Unauthorized | Verify API token or PAT            |
| 403         | Forbidden    | Check Jira project permissions     |
| 404         | Not Found    | Verify issue key or project exists |
| 429         | Rate Limited | Wait and retry                     |

## External Resources

<CardGroup cols={2}>
  <Card title="Jira Cloud REST API" icon="book" href="https://developer.atlassian.com/cloud/jira/platform/rest/v3/">
    Official API documentation for Jira Cloud
  </Card>

  <Card title="Jira Data Center REST API" icon="book" href="https://docs.atlassian.com/software/jira/docs/api/REST/latest/">
    Official API documentation for Jira Data Center
  </Card>

  <Card title="Atlassian API Tokens" icon="key" href="https://id.atlassian.com/manage-profile/security/api-tokens">
    Generate API tokens for Jira Cloud
  </Card>

  <Card title="MCP Specification" icon="robot" href="https://modelcontextprotocol.io">
    Model Context Protocol specification
  </Card>
</CardGroup>