> ## Documentation Index
> Fetch the complete documentation index at: https://docs.prisme.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Jira (legacy)
> Search, create, and manage Jira issues from Agent Factory agents and Builder workflows — Cloud and Data Center
This is the **legacy** Jira connector (static Basic-Auth / PAT credential held by the installing workspace, flat tool names). It is superseded by the new **[Jira](/apps-store/marketplace/connectors/jira)** connector (App+MCP, tenant-context, central Atlassian 3LO OAuth, with issues / search / projects / users / metadata / agile / attachments entity tools). Use the new Jira connector for any new work — this page is kept for existing installations only.
The Jira connector exposes [Atlassian Jira](https://www.atlassian.com/software/jira) issue tracking as tools, supporting both **Jira Cloud** and **Jira Data Center** deployments. It can be consumed two ways: as a remote MCP server that **Agent Factory** agents call as tools, or as a Builder app whose instructions you call directly from DSUL. Authentication is a **static credential** held by the installing workspace — Basic Auth (Atlassian account email + API token) for Cloud, or a Bearer **Personal Access Token (PAT)** for Data Center — resolved server-side so the credential is never exposed to the agent.
Search with JQL, then create, read, update and delete issues — including custom fields once they are resolved by id.
List and apply status transitions, add comments and attach files to move issues through their workflow.
List accessible projects, inspect create screens, and discover field ids (including custom fields) before writing.
## Who is this for?
This connector is used by three different roles. Jump to the section that matches yours — each one is self-contained.
You build agents in **Agent Factory** and want them to use Jira. → *Agent builder* tab.
You run the platform and want to know what to set up once for everyone. → *Platform admin setup* accordion below.
You write Builder automations (DSUL) that call Jira operations directly. → *Workspace builder* tab.
## Prerequisites
* A **Jira Cloud** or **Jira Data Center** instance, and an account with permission on the projects you intend to use.
* Your **base URL** — for Cloud `https://yoursite.atlassian.net`, for Data Center `https://jira.yourcompany.com`.
* **For Jira Cloud:** an **Atlassian account email** and an **API token**, generated at [Atlassian API Tokens](https://id.atlassian.com/manage-profile/security/api-tokens). The connector uses these for Basic Auth.
* **For Jira Data Center:** a **Personal Access Token (PAT)**, generated under your Jira profile **Personal Access Tokens**. The connector sends it as a Bearer token.
**Goal:** Jira is a **per-workspace** connector — each workspace pastes its own Jira credential (see the *Workspace builder* tab), so there is **no platform-wide credential to provision** and no central OAuth client.
There is no shared Jira credential for this connector. The base URL, email/API token (Cloud) or PAT (Data Center) always live in the consuming workspace's app configuration. The only optional platform task is to publish Jira as a reusable **capability** in AI Governance so agent builders can enable it from the catalog instead of pasting a raw MCP endpoint.
## Declare the capability in AI Governance (optional)
Create (or edit) the **Jira** capability.
Set the capability's MCP server URL to the connector's **MCP Endpoint** (the workspace running the connector), and set its **Scope** to:
```text theme={null}
context_id,agent_id,user_id
```
The `agent_id` in the scope is what lets the connector identify the calling agent.
Once created, the capability appears in the capability picker for agent builders in your organization. Access to the catalog follows your organization's existing roles; there is no per-capability role grant for this static-credential connector. Each workspace running the connector still owns its Jira credential.
Declaring the capability makes the connector **available**; it does not provision any credential. This connector follows the **static-credential model** — the Jira base URL and token live in the consuming workspace's app configuration. There is **no OAuth auth-config JSON** to attach in Governance.
***
## Agent builder
**Goal:** let an agent you build in Agent Factory search and manage Jira through MCP tools.
Before an agent can call the connector, a *Workspace builder* must have installed and configured the Jira app in a workspace (see the *Workspace builder* tab). Optionally, a *Platform admin* may have published a Jira capability in AI Governance (see the *Platform admin setup* accordion above).
This connector runs on a **static credential** owned by the workspace that installed it. Your agent is identified by the `agent_id` that Agent Factory injects through the capability *Scope*; the Jira credential itself is resolved server-side and is never exposed to the agent.
Follow the *Workspace builder* tab: install **Jira** in your workspace and provide the base URL, deployment type, and credential (Cloud email + API token, or Data Center PAT).
In your agent, add a capability pointing at the workspace's **MCP Endpoint** URL, and set its **Scope** to:
```text theme={null}
context_id,agent_id,user_id
```
The `agent_id` lets the connector identify your agent. The credential is resolved from the workspace configuration server-side.
Tell the agent the tools exist and when to use them. See *Brief the agent in its system prompt* below.
## Brief the agent in its system prompt
A short brief keeps the agent from guessing field ids or skipping discovery. Copy-pasteable starter:
```text theme={null}
You have access to the Jira MCP server. Use searchJira with a JQL query to find issues, getIssue to read one by key (e.g. DEV-123), and createIssue / updateIssue / deleteIssue to manage them. To move an issue, call getTransitions then transitionIssue with the chosen transitionId. Use addComment and addAttachment for collaboration. Before writing a custom field, resolve its id with listFields (customOnly: true) and confirm availability with listCreateIssueTypes / getCreateIssueFields. Confirm with the user before any create, update, delete or transition.
```
**Legacy AI Knowledge agents** (no native MCP picker): add the connector under **Advanced > Tools > MCP** and paste the **MCP Endpoint** URL. The agent is still identified by the capability *Scope* and the credential is resolved from the workspace configuration.
## 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 |
### Field Discovery
| Tool | Description |
| ---------------------- | ---------------------------------------------------------------------- |
| `listFields` | List or search Jira fields, including custom fields |
| `listCreateIssueTypes` | List issue types available when creating issues in a project |
| `getCreateIssueFields` | Get fields available on the create screen for a project and issue type |
### 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` | Store Jira credentials for the calling user (per-user connection) |
## Output Formats
All tools accept an `outputFormat` argument that controls the MCP response shape:
* **`verbose`** (default) — human-readable text optimized for LLM consumption
* **`structured`** — machine-readable JSON in `structuredContent`
* **`both`** — both the text and the structured content
## Tool Details
### searchJira
```json theme={null}
{
"name": "searchJira",
"arguments": {
"jql": "project = DEV AND status = \"In Progress\"",
"maxResults": 10
}
}
```
| Parameter | Required | Description |
| --------------- | -------- | --------------------------------------------------------------------- |
| `jql` | Yes | JQL query string (project, status, assignee, labels, text search, …). |
| `maxResults` | No | Max results per page (default 50). |
| `nextPageToken` | No | Cursor for the next page of results. |
| `fields` | No | Comma-separated list of fields to return. |
### getIssue
```json theme={null}
{
"name": "getIssue",
"arguments": {
"issueKey": "DEV-123"
}
}
```
| Parameter | Required | Description |
| ---------- | -------- | ------------------------------ |
| `issueKey` | Yes | The issue key, e.g. `DEV-123`. |
### createIssue
```json theme={null}
{
"name": "createIssue",
"arguments": {
"projectKey": "DEV",
"issueType": "Task",
"summary": "Implement new feature",
"description": "Detailed description here",
"priority": "High",
"fields": {
"customfield_10016": 8
}
}
}
```
| Parameter | Required | Description |
| ------------- | -------- | ----------------------------------------------------------------------------------------------------------- |
| `projectKey` | Yes | Target project key. |
| `issueType` | Yes | Issue type name (e.g. `Task`, `Bug`, `Story`). |
| `summary` | Yes | Issue summary / title. |
| `description` | No | Issue description. |
| `priority` | No | Priority name (e.g. `High`). |
| `fields` | No | Map of additional fields by id, e.g. `customfield_10016`. Resolve custom-field ids with `listFields` first. |
### listFields
```json theme={null}
{
"name": "listFields",
"arguments": {
"query": "testPrismeField",
"customOnly": true,
"maxResults": 50
}
}
```
| Parameter | Required | Description |
| ------------ | -------- | -------------------------------------- |
| `query` | No | Substring to match field names. |
| `customOnly` | No | Restrict to custom fields when `true`. |
| `maxResults` | No | Max fields to return. |
Use the returned `customfield_...` id in `createIssue` or `updateIssue` only after Jira reports the field as available for that project and issue type (confirm with `listCreateIssueTypes` / `getCreateIssueFields`).
### transitionIssue
```json theme={null}
{
"name": "transitionIssue",
"arguments": {
"issueKey": "DEV-123",
"transitionId": "31",
"comment": "Moving to In Progress"
}
}
```
| Parameter | Required | Description |
| -------------- | -------- | ------------------------------------------- |
| `issueKey` | Yes | The issue to transition. |
| `transitionId` | Yes | The transition id from `getTransitions`. |
| `comment` | No | Optional comment added with the transition. |
### configureJira
```json theme={null}
{
"name": "configureJira",
"arguments": {
"baseUrl": "https://yoursite.atlassian.net",
"type": "cloud",
"email": "you@example.com",
"apiToken": "your-api-token"
}
}
```
| Parameter | Required | Description |
| --------------------- | --------------- | ------------------------- |
| `baseUrl` | Yes | Jira base URL. |
| `type` | Yes | `cloud` or `datacenter`. |
| `email` | For Cloud | Atlassian account email. |
| `apiToken` | For Cloud | Atlassian API token. |
| `personalAccessToken` | For Data Center | PAT for Jira Data Center. |
Stores the credential securely in the calling user's platform secrets, so a per-user connection persists across requests without relying on the shared workspace credential.
## Workspace builder
**Goal:** install the connector in a workspace, configure the Jira credential, and call Jira operations from your automations.
## Installation
1. Go to **Apps** in your workspace
2. Search for **Jira** and install it
3. Configure the app instance with your Jira base URL, deployment type, and credential (Cloud email + API token, or Data Center PAT)
## Configuration
| Field | Description |
| ------------------------- | ------------------------------------------------------------------------------------------------------------ |
| **Jira Base URL** | The instance URL — `https://yoursite.atlassian.net` (Cloud) or `https://jira.yourcompany.com` (Data Center). |
| **Deployment Type** | `cloud` or `datacenter`. |
| **Atlassian Email** | Cloud only — the Atlassian account email used with the API token. Stored as a workspace secret. |
| **API Token** | Cloud only — the Atlassian API token (Basic Auth). Stored as a workspace secret. |
| **Personal Access Token** | Data Center only — the PAT sent as a Bearer token. Stored as a workspace secret. |
The connector resolves credentials with the following priority, so the same instance works for shared and per-user setups:
| Auth source | What you provide | Best for |
| -------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------- |
| Workspace config (default) | Base URL + type + Cloud email/API token or Data Center PAT | Shared workspace connection — all callers use the same Jira account |
| Per-user secrets | Call `configureJira` once per user | A personal Jira connection scoped to the calling user |
Credentials are stored as workspace (or per-user) secrets and resolved server-side. Jira Cloud uses Basic Auth (email + API token); Jira Data Center uses a Bearer PAT.
## Available Instructions
Every instruction resolves credentials from the workspace configuration (or per-user secrets).
### Issues
| Instruction | Description | Returns |
| ------------- | --------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
| `searchJira` | Search issues with a `jql` query; page with `maxResults`/`nextPageToken`, narrow with `fields`. | `{ issues: [{ key, fields }], nextPageToken }` |
| `getIssue` | Fetch a single issue by `issueKey` (e.g. `DEV-123`). | `{ key, fields: { summary, status, … } }` |
| `createIssue` | Create an issue from `projectKey`, `issueType`, `summary` (+ optional `description`, `priority`, `fields` map). | `{ id, key, self }` |
| `updateIssue` | Update an existing issue by `issueKey`; pass changed `fields`. | Empty (HTTP 204) |
| `deleteIssue` | Delete an issue by `issueKey`. | Empty (HTTP 204) |
### Field Discovery
| Instruction | Description | Returns |
| ---------------------- | ------------------------------------------------------------------------------------- | --------------------------------------------- |
| `listFields` | List or search Jira fields by `query`; `customOnly: true` restricts to custom fields. | `[{ id, name, custom, schema }]` |
| `listCreateIssueTypes` | List issue types available when creating issues in a project. | `{ issueTypes: [{ id, name }] }` |
| `getCreateIssueFields` | Get fields available on the create screen for a `projectKeyOrId` + `issueTypeId`. | `{ fields: [{ fieldId, required, schema }] }` |
### Workflow
| Instruction | Description | Returns |
| ----------------- | ------------------------------------------------------------------------------------ | ------------------------------------- |
| `getTransitions` | Get available status transitions for an `issueKey`. | `{ transitions: [{ id, name, to }] }` |
| `transitionIssue` | Change an issue's status by `issueKey` + `transitionId`, with an optional `comment`. | Empty (HTTP 204) |
| `addComment` | Add a comment to an issue by `issueKey`; `body` is the comment text. | `{ id, body, author, created }` |
| `addAttachment` | Attach a file to an issue by `issueKey`. | `[{ id, filename, size }]` |
### Projects
| Instruction | Description | Returns |
| -------------- | --------------------------------------------------- | ----------------------------------- |
| `listProjects` | List projects accessible to the configured account. | `[{ id, key, name }]` |
| `getProject` | Get a project's details by key or id. | `{ id, key, name, projectTypeKey }` |
### Configuration
| Instruction | Description | Returns |
| --------------- | ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------- |
| `configureJira` | Store Jira credentials in the calling user's platform secrets (Cloud email + API token, or Data Center PAT). | `{ success, configuration: { baseUrl, type } }` |
`Returns` shows the shape of the operation output.
## 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 with a custom field:**
Jira custom fields must already exist and be available for the target project and issue type. Resolve the technical field id with `listFields`, then pass values through `fields`.
```yaml theme={null}
- Jira.listFields:
query: testPrismeField
customOnly: true
output: fieldLookup
- Jira.createIssue:
projectKey: KAN
issueType: Task
summary: Create issue with a custom labels field
fields:
customfield_10104:
- prisme-test
- label-type
output: newIssue
```
If Jira rejects a custom field during creation, verify the field context and the create screen/layout. For team-managed projects the field must be added to the work-type layout — confirm availability with `listCreateIssueTypes` and `getCreateIssueFields` before creating.
**Transition an issue and comment:**
```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
```
***
## Error Handling
| HTTP Status | Error | Solution |
| ----------- | ------------- | ----------------------------------------------------------------------------------------------------------------------- |
| 401 | Unauthorized | Verify the API token (Cloud) or PAT (Data Center) and the account email. |
| 403 | Forbidden | Check the account's permissions on the target Jira project. |
| 404 | Not Found | Verify the issue key, project key, or transition id exists and is visible to the account. |
| 422 | Unprocessable | A field value is invalid or a required field is missing — resolve field ids with `listFields` / `getCreateIssueFields`. |
| 429 | Rate Limited | Wait and retry. |
| 500 | Server error | Transient Jira error — retry shortly. |
### Common Issues
**"Not configured" / "Jira not configured"** — No base URL or credential is set. Open the Jira app configuration and provide the base URL, deployment type, and the matching credential (Cloud email + API token, or Data Center PAT). Agent builders should confirm with the workspace owner that the connector is configured.
**"Missing credentials"** — The deployment type is set but the matching secret is empty: Cloud needs `email` + `apiToken`; Data Center needs `personalAccessToken`. Fill the missing field in the app configuration.
**"Invalid type"** — `type` is neither `cloud` nor `datacenter`. Set it to one of those two values.
**"The calling agent could not be identified"** — The MCP capability *Scope* does not declare `agent_id`. Set the Scope to `context_id,agent_id,user_id` on the capability.
**Custom field rejected on create** — The field is not on the create screen for that project/issue type, or you used the wrong id. Resolve the id with `listFields` (`customOnly: true`), then confirm availability with `listCreateIssueTypes` and `getCreateIssueFields`. For team-managed projects, add the field to the work-type layout in Jira first.
## External Resources
Official API documentation for Jira Cloud.
Official API documentation for Jira Data Center.
Generate API tokens for Jira Cloud.
Learn how Agent Factory agents consume MCP tools in Prisme.ai.