Jira - Prisme.ai

The Jira app provides read/write access to Atlassian Jira Cloud through the official REST API v3 (platform) and Agile 1.0 (Jira Software). 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. The MCP surface groups every operation into seven entity tools (issues, search, projects, users, metadata, agile, attachments), each driven by an action argument, and runs in the tenant app-instance context (it resolves the installing workspace’s own credentials and gates which agents may call it). Authentication is per-user and supports several modes:

Per-user OAuth2 — central client (oauthCentral, recommended) — one Atlassian 3LO OAuth app is registered once by the platform maintainer; every end user signs in with their own Atlassian account. Nothing to register per tenant: each workspace just installs the app and clicks Connect.
Per-user OAuth2 — tenant client (oauth) — paste your own Atlassian OAuth client ID/secret in the connector config app. Each user signs in with their own account against your client (PKCE authorization-code, 3LO).
API token — HTTP Basic (apiToken) — an Atlassian account email + API token + your *.atlassian.net site. A single shared service identity, no interactive sign-in.
Direct access token (accessToken) — a caller-managed Atlassian access token, used as-is with no exchange.

Issues & workflow

Search with JQL, create, read, update, delete, assign and comment on issues; list and apply workflow transitions.

Projects & metadata

List projects, components, versions and statuses; discover fields, issue types, priorities and create-screen metadata before writing.

Per-user Atlassian OAuth

Per-user 3LO OAuth (central or tenant client), an HTTP Basic API token, or a direct access token — resolved server-side.

Who is this for?

This connector is used by three different roles. Jump to the section that matches yours — each one is self-contained.

Agent builder

You build agents in Agent Factory and want them to read and act on Jira. → Agent builder tab.

Platform admin

You run the platform and set up the shared Atlassian OAuth client once for everyone. → Platform admin setup accordion below.

Workspace builder

You write Builder automations (DSUL) that call Jira operations directly. → Workspace builder tab.

Prerequisites (Atlassian side)

An Atlassian Jira Cloud site (https://yoursite.atlassian.net) and an account with permission on the projects you intend to use.
For the OAuth modes: an OAuth 2.0 (3LO) app registered in the Atlassian Developer Console, with the Jira platform REST API added and the scopes below granted. For the apiToken mode instead: an Atlassian account email + an API token generated at Atlassian API Tokens.
The base URL is resolved automatically: OAuth modes call https://api.atlassian.com/ex/jira/{cloudId} (the cloudId is discovered from the granted site); the apiToken mode calls https://{site}.atlassian.net directly.

The OAuth scopes requested by default are the classic Jira platform scopes, which cover every platform operation (issues, search, projects, users, metadata, attachments):

read:jira-work
write:jira-work
read:jira-user
manage:jira-project
manage:jira-configuration
offline_access

Agile boards/sprints/backlog need a different, fully-granular OAuth app — they do not work with the classic scopes above. The Jira Agile 1.0 API (the agile tool: boards, sprints, backlog) only accepts the granular Jira Software scopes (read:board-scope:jira-software, write:board-scope:jira-software, read:sprint:jira-software, write:sprint:jira-software) and refuses any token that also carries a classic scope (“scope does not match”). So enabling Agile requires migrating the entire Atlassian app to granular scopes (~30-40 verbose scopes covering all platform operations too), which is incompatible with the simple classic setup. With the default classic scopes, the seven agile operations are not usable. This is an Atlassian platform limitation, not a connector limitation — see the Platform admin setup accordion for the trade-off.

Platform admin (Governance) — one-time platform setup

Goal: two one-time tasks — (1) configure the shared central Atlassian OAuth client so every workspace lets its users sign in with their own Atlassian account, and (2) expose Jira as a reusable capability in AI Governance so agent builders can pick it without pasting endpoint URLs.

1. Configure the connector

In the Atlassian Developer Console, create an app → Authorization > OAuth 2.0 (3LO), and set the Callback URL to the core workspace callback:

<api-url>/workspaces/slug:jira-next/webhooks/oauthCallback

(e.g. https://api.studio.prisme.ai/v2/workspaces/slug:jira-next/webhooks/oauthCallback on production — <api-url> is the production API URL. Copy the exact URI from the connector’s configuration app, which renders it for you.) Then under Permissions, add the Jira platform REST API and enable the scopes listed in Prerequisites. Note the Client ID and Secret from Settings.

Choose classic or granular scopes — and decide about Agile

Atlassian enforces classic XOR granular scopes per product in the developer console: the classic scopes (read:jira-work, write:jira-work, read:jira-user, manage:jira-project, manage:jira-configuration) do not appear in the granular list and cannot be mixed with granular Jira Software scopes on the same token.

For the 36 platform operations (issues, search, projects, users, metadata, attachments) — keep the classic scope set above. Simple, recommended.
To additionally enable the agile tool (boards / sprints / backlog) — you must migrate the app to a fully-granular set (every platform scope plus read:board-scope:jira-software, write:board-scope:jira-software, read:sprint:jira-software, write:sprint:jira-software), because the Agile API rejects a token that also carries any classic scope. This is verbose (~30-40 scopes) and is the only way to use Agile.

The connector requests exactly the scopes set in its Scopes field (the central scopes entered in step 3, overridable per workspace) — not whatever is enabled on the Atlassian app. Enabling more scopes in the Atlassian developer console has no effect until you also add them to the connector’s Scopes field. Conversely the Scopes field can never grant a permission the Atlassian app does not expose.

Enter the credentials through the configuration app

Open the central jira-next workspace and launch its Configuration app — <studio>/apps/jira-next (e.g. https://studio.prisme.ai/apps/jira-next), also linked as Configuration app on the installed instance. Switch to the maintainer view and follow the in-app instructions to paste the Client ID, Client Secret and the Scopes — the app stores them in the core workspace’s secrets for you. Do not edit Studio’s raw Secrets by hand. These credentials stay in the jira-next workspace and are never exposed to tenants or end users; token exchange is proxied through the core centralTokenExchange webhook so the client secret never leaves the core workspace.

One Atlassian OAuth app can serve both Jira and Confluence. A single Atlassian app (one Client ID/Secret) can have both the Jira platform REST API and the Confluence API enabled. Each connector requests its own Scopes, so Jira can stay on classic scopes while Confluence uses its required granular scopes on the very same app — point both connectors’ config apps at the same Client ID/Secret and give each its own Scopes field.

Tell workspaces to use the central client

Each consuming workspace selects auth mode oauthCentral in the connector configuration app (no client id/secret to enter on their side). Their users then just click Connect.

2. Declare the capability in AI Governance

Generic connectors — broad tool surfaces meant to be shared across many agents, like Jira — are best exposed as a named capability in AI Governance. Agent builders then enable that capability on their agents instead of pasting a raw MCP endpoint.

Open AI Governance > Capabilities

Create (or edit) the Jira capability.

Point it at the MCP endpoint

Set the capability’s MCP server URL to the connector’s MCP Endpoint, and set its Scope to:

context_id,agent_id,user_id

The agent_id in the scope is what lets the connector identify and authorize the calling agent.

Make it available to agent builders

Once created, the capability appears in the capability picker for agent builders in your organization, who enable it on their agents. Access to the catalog follows your organization’s existing roles; there is no per-capability role grant.

Smoke-test

From an agent that has the capability, in a workspace configured for oauthCentral, trigger any tool. The user is prompted to connect once (Atlassian sign-in); subsequent calls reuse the stored token transparently and refresh it automatically.

Declaring the capability makes the connector available; it does not by itself authorize a specific agent. This connector follows the tenant-context model — which agents may actually call it is gated per-workspace by the authorized-agents allowlist in the configuration app (see the Workspace builder tab). There is also no OAuth auth-config JSON to attach in Governance: connect / status / disconnect are handled by the connector’s own webhooks, wired automatically.

Agent builder (Agent Factory)
Workspace builder (DSUL)

Agent builder

Goal: let an agent you build in Agent Factory read and act on 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), and — for the central OAuth mode — a Platform admin must have provisioned the shared OAuth client (see the Platform admin setup accordion above).

This connector runs in the tenant app-instance context: your agent is authorized two ways at once — it is identified by the agent_id that Agent Factory injects through the capability Scope, and that agent must appear in the connector’s authorized-agents allowlist (managed in the configuration app). The Atlassian token itself is resolved server-side from the configured auth mode.There are two ways to wire it up. Pick based on how much isolation you need.

Option A — Enable the shared capability from the catalog

The fastest path: a Platform admin has already published a Jira capability (see the Platform admin setup accordion above, §2), so you just pick it from the catalog.

Open your agent in Agent Factory

Open the agent you want to extend and go to its capabilities / tools.

Add the Jira capability

Browse the capability catalog, select Jira, and enable it. The MCP endpoint URL and the Scope (context_id,agent_id,user_id) are already wired by the admin — nothing to paste, and the shared instance accepts every agent, so there is no allowlist step on your side.

Connect an Atlassian account (OAuth modes)

On the first tool call, an unconnected user is prompted to sign in — Agent Factory surfaces a connect_url. The apiToken and accessToken modes need no per-user sign-in.

Convenient, but your agent runs against a shared, platform-managed instance: its Atlassian credentials are owned by someone else and the instance accepts every agent that is granted the capability. Prefer Option B for anything beyond quick experiments.

Option B — Run it from your own workspace (recommended)

For production agents, install the connector in your own workspace and point the agent at that workspace’s MCP endpoint.

Prefer this mode for security. Because the MCP runs in your app-instance context, the Atlassian credentials, the per-user OAuth tokens and the authorized-agents allowlist are all scoped to your workspace — not shared platform-wide. You decide exactly which agents may call it and which Atlassian account / auth mode backs them, and a misconfiguration elsewhere can never expose your data. The shared catalog capability (Option A) is a broad surface many agents can reach; your own workspace is an isolated, least-privilege boundary.

Install and configure the connector in your workspace

Follow the Workspace builder tab: install JiraNext in your workspace, open its Configuration app, choose the auth mode and connect an Atlassian account.

Allowlist your agent

In that workspace’s config app, open Authorized agents and tick your agent (the Install capability button does this for you).

Add the MCP capability to your agent

In your agent, add a capability pointing at your workspace’s MCP Endpoint URL, and set its Scope to:

context_id,agent_id,user_id

The agent_id is what lets the connector identify and authorize your agent — without it, every call is rejected with an explicit “agent could not be identified” message. This Scope is separate from the Atlassian OAuth scopes.

Connect an Atlassian account (OAuth modes)

On the first tool call, the user is prompted to sign in (or uses Connect in the config app).

Brief the agent in its system prompt

Whichever option you pick, wiring the capability is not enough — the agent must know the MCP exists and when to use it. Copy-pasteable starter:

You have access to the Jira MCP server (tools: issues, search, projects, users, metadata, agile, attachments). Each tool takes an `action` argument. Use `search` (action `jql`) to find issues, `issues` (action `get`) to read one by key (e.g. PROJ-123), and `issues` create/update/delete/assign to manage them. To move an issue, call `issues` getTransitions then doTransition. Rich text (description, comment body) uses Atlassian Document Format (ADF), and users are referenced by `accountId` (resolve with the `users` tool). Before creating an issue, discover the required fields with `metadata` createmeta then createmetaFields. Confirm with the user before any create, update, delete, assign 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 still has to be allowlisted in the config app and its identity propagated so the connector can read its agent_id.

Restricting to read-only (least privilege). Jira tools cover both reads and writes (create / update / delete / assign issues, transitions, comments). The requested OAuth scopes are the grant, so the connector only obtains what the Scopes field in the configuration app asks for. To allow only read access, set a read-only scope list:

read:jira-work read:jira-user offline_access

(Drop write:jira-work, manage:jira-project and manage:jira-configuration.) With central OAuth (oauthCentral) you do not create your own Atlassian client — keep oauthCentral and just enter the read-only scopes; your tenant scope overrides the platform default (the central app must expose those read scopes). Write calls are then rejected by Atlassian with 403. Note this is set at the workspace level — a workspace editor can widen it again; a provider-side restriction (a read-only Atlassian account/permission scheme) is the only hard guarantee. For the apiToken mode, restrict at the provider instead by backing the connection with a Jira account that has read-only project permissions.

Available Tools

Each tool takes an action argument selecting the concrete operation, plus the per-action parameters.

Tool	Description
`issues`	Jira issues (REST v3). Actions: `get`, `create`, `update`, `delete`, `assign`, `getTransitions`, `doTransition`, `getComments`, `addComment`, `getEditMeta`. Rich text uses ADF; users by `accountId`.
`search`	Search issues with JQL (`POST /rest/api/3/search/jql`). Action: `jql`. Token-based pagination via `nextPageToken`.
`projects`	Jira projects. Actions: `list`, `get`, `components`, `versions`, `statuses`.
`users`	Jira users (identified by `accountId`). Actions: `search`, `get`, `myself`, `assignable`.
`metadata`	Discover fields, types and create metadata. Actions: `fields`, `issuetypes`, `priorities`, `statuses`, `createmeta`, `createmetaFields`.
`agile`	Jira Software boards, sprints & backlog (Agile 1.0). Actions: `boards`, `getBoard`, `boardIssues`, `sprints`, `getSprint`, `sprintIssues`, `backlog`. Requires a fully-granular Jira Software OAuth setup (see Prerequisites).
`attachments`	Issue attachments. Actions: `getMeta`, `delete` (`add` is not available inline — upload binaries via Jira directly).

Output Formats

Every tool accepts 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

search

{
  "name": "search",
  "arguments": {
    "action": "jql",
    "body": {
      "jql": "project = DEV AND status = \"In Progress\" ORDER BY updated DESC",
      "maxResults": 25,
      "fields": ["summary", "status", "assignee"]
    }
  }
}

Parameter	Required	Description
`action`	Yes	`jql`.
`body`	Yes	Search request `{ jql, maxResults (≤100), nextPageToken, fields: [..], expand }`. Always pass `fields` to limit the payload.
`body.nextPageToken`	No	Cursor from a previous response to fetch the next page (the legacy `startAt` is not used here).

issues

{
  "name": "issues",
  "arguments": {
    "action": "create",
    "body": {
      "fields": {
        "project": { "key": "DEV" },
        "issuetype": { "name": "Task" },
        "summary": "Implement new feature",
        "description": {
          "type": "doc",
          "version": 1,
          "content": [
            { "type": "paragraph", "content": [{ "type": "text", "text": "Detailed description here." }] }
          ]
        }
      }
    }
  }
}

Parameter	Required	Description
`action`	Yes	One of `get`, `create`, `update`, `delete`, `assign`, `getTransitions`, `doTransition`, `getComments`, `addComment`, `getEditMeta`.
`issueIdOrKey`	For everything but create	Issue id or key, e.g. `DEV-123`.
`body`	For create/update/assign/doTransition/addComment	Jira v3 JSON body. Create/update use `{ fields }` (or `{ update }`); assign `{ accountId }`; doTransition `{ transition: { id } }`; addComment `{ body: <ADF doc> }`.
`fields`	No	`fields` query param (comma-separated list, or `*all`) for `get`.
`deleteSubtasks`	No	`delete` only — `"true"` to delete subtasks.

metadata

{
  "name": "metadata",
  "arguments": {
    "action": "createmetaFields",
    "projectIdOrKey": "DEV",
    "issueTypeId": "10002"
  }
}

Parameter	Required	Description
`action`	Yes	One of `fields`, `issuetypes`, `priorities`, `statuses`, `createmeta`, `createmetaFields`.
`projectIdOrKey`	For createmeta/createmetaFields	Project id or key.
`issueTypeId`	For createmetaFields	Issue type id (from `createmeta`).

Resolve a custom field’s technical id (customfield_…) with metadata fields, then confirm it is on the create screen for that project + issue type with createmeta → createmetaFields before passing it in issues create/update.

agile

{
  "name": "agile",
  "arguments": {
    "action": "sprintIssues",
    "sprintId": "42",
    "jql": "assignee = currentUser()",
    "fields": "summary,status",
    "maxResults": 50
  }
}

Parameter	Required	Description
`action`	Yes	One of `boards`, `getBoard`, `boardIssues`, `sprints`, `getSprint`, `sprintIssues`, `backlog`.
`boardId`	For getBoard/boardIssues/sprints/backlog	Agile board id.
`sprintId`	For getSprint/sprintIssues	Sprint id.
`state`	No	`sprints` only — `future`, `active` or `closed`.
`jql` / `fields`	No	Optional JQL filter and comma-separated field list (boardIssues, sprintIssues, backlog).

The agile tool needs a fully-granular Jira Software OAuth app (see Prerequisites and the Platform admin setup accordion). With the default classic scopes, every agile action fails with an Atlassian “scope does not match” error.

users

{
  "name": "users",
  "arguments": {
    "action": "assignable",
    "project": "DEV",
    "query": "ada"
  }
}

Parameter	Required	Description
`action`	Yes	One of `search`, `get`, `myself`, `assignable`.
`query`	For search/assignable	Name or email fragment.
`accountId`	For get	Atlassian `accountId`.
`project` / `issueKey`	For assignable	Scope assignable users to a project or issue.

Reference users by accountId (not username) in every issue body — myself returns the connected user’s own accountId.

Workspace builder

Goal: install the connector in a workspace, configure authentication and the agent allowlist, and call Jira operations from your automations.

Installation

Go to Apps in your workspace
Search for JiraNext and install it
Open the Configuration app (the link auto-populated on install) to choose the auth mode, provide credentials, connect, and allow the agents that may call the connector

Configuration

Field	Description
Configuration app	Auto-populated on install — open this link to configure authentication (mode + credentials), connect an Atlassian account (OAuth modes), and manage the authorized-agents allowlist.

The configuration app drives everything; the app instance itself has no per-field credential form. From it you pick one of:

Auth mode	What you provide	Best for
`oauthCentral`	Nothing — just click Connect	Workspaces on a platform where the admin set up the central Atlassian client
`oauth`	Your own Atlassian Client ID + Secret (callback URI `<api-url>/workspaces/slug:jira-next/webhooks/oauthCallback`) + Scopes	You manage your own Atlassian OAuth app
`apiToken`	Atlassian account email + API token + site (`yoursite.atlassian.net`)	A single shared service identity, no interactive sign-in
`accessToken`	A pre-minted Atlassian access token	Short-lived / caller-managed tokens

Credentials are provisioned into the workspace’s Secrets by the onInstall flow and resolved server-side. The agent allowlist (Authorized agents) gates which Agent Factory agents may call the MCP endpoint — see the Agent builder tab. The OAuth Scopes field is what the connector actually requests (default classic scopes; see Prerequisites); set a read-only list there to restrict writes.

Available Instructions

Every instruction resolves credentials from the workspace configuration. Operations are grouped by resource; the MCP server exposes the same operations behind the seven entity tools (see the Agent builder tab).

Issues

Instruction	Description	Returns
`getIssue`	Fetch one issue by `issueIdOrKey` (e.g. `DEV-123`); narrow with `fields`/`expand`.	`{ id, key, fields: { summary, status, … } }`
`createIssue`	Create an issue from `body.fields` (`{ project, issuetype, summary, … }`; ADF for rich text).	`{ id, key, self }`
`updateIssue`	Edit an issue by `issueIdOrKey`; `body` = `{ fields }` or `{ update }`. `notifyUsers: "false"` suppresses mail.	Empty (HTTP 204)
`deleteIssue`	Delete an issue by `issueIdOrKey`; `deleteSubtasks: "true"` to cascade.	Empty (HTTP 204)
`assignIssue`	Set the assignee by `issueIdOrKey`; `body` = `{ accountId }`.	Empty (HTTP 204)
`getTransitions`	List the available workflow transitions for an `issueIdOrKey`.	`{ transitions: [{ id, name, to }] }`
`doTransition`	Move the issue by `issueIdOrKey`; `body` = `{ transition: { id } }`.	Empty (HTTP 204)
`getComments`	List comments on an `issueIdOrKey`; page with `startAt`/`maxResults`.	`{ comments: [{ id, body, author, created }], total }`
`addComment`	Add a comment to an `issueIdOrKey`; `body` = `{ body: <ADF doc> }`.	`{ id, body, author, created }`
`getEditMeta`	Editable-fields metadata for an `issueIdOrKey`.	`{ fields: { <fieldId>: { required, schema, … } } }`

Search

Instruction	Description	Returns
`searchJql`	Run a JQL search; `body` = `{ jql, maxResults (≤100), nextPageToken, fields: [..], expand }`.	`{ issues: [{ id, key, fields }], nextPageToken }`

Projects

Instruction	Description	Returns
`listProjects`	List/search projects (paginated); `query`, `startAt`, `maxResults`, `orderBy`, `expand`.	`{ values: [{ id, key, name }], total, isLast }`
`getProject`	Get a project by `projectIdOrKey`.	`{ id, key, name, projectTypeKey, lead }`
`getProjectComponents`	List a project’s components by `projectIdOrKey`.	`[{ id, name, lead }]`
`getProjectVersions`	List a project’s versions by `projectIdOrKey`.	`[{ id, name, released, archived }]`
`getProjectStatuses`	List the issue-type statuses of a project by `projectIdOrKey`.	`[{ id, name, statuses: [{ id, name }] }]`

Users

Instruction	Description	Returns
`searchUsers`	Find users by name/email fragment `query`.	`[{ accountId, displayName, emailAddress }]`
`getUserByAccountId`	Get a user by `accountId`.	`{ accountId, displayName, active, … }`
`getMyself`	The current authenticated user.	`{ accountId, displayName, emailAddress }`
`findAssignableUsers`	Users assignable to a `project`/`issueKey`; filter with `query`.	`[{ accountId, displayName }]`

Metadata

Instruction	Description	Returns
`listFields`	List all fields (system + custom).	`[{ id, name, custom, schema }]`
`listIssueTypes`	List all issue types.	`[{ id, name, subtask }]`
`listPriorities`	List priorities (paginated); `startAt`, `maxResults`.	`{ values: [{ id, name }], total }`
`listStatuses`	List all statuses.	`[{ id, name, statusCategory }]`
`getCreateMetaIssueTypes`	Issue types creatable in a `projectIdOrKey`.	`{ issueTypes: [{ id, name }] }`
`getCreateMetaFields`	Fields required to create a given type in `projectIdOrKey` + `issueTypeId`.	`{ fields: [{ fieldId, required, schema }] }`

Agile

Instruction	Description	Returns
`listBoards`	List boards; filter by `type`, `name`, `projectKeyOrId`.	`{ values: [{ id, name, type }], isLast }`
`getBoard`	Get a board by `boardId`.	`{ id, name, type, location }`
`getBoardIssues`	Issues on a `boardId`; optional `jql`, `fields`.	`{ issues: [{ id, key, fields }], total }`
`listSprints`	List a board’s sprints by `boardId`; `state` = `future`/`active`/`closed`.	`{ values: [{ id, name, state }], isLast }`
`getSprint`	Get a sprint by `sprintId`.	`{ id, name, state, startDate, endDate }`
`getSprintIssues`	Issues in a `sprintId`; optional `jql`, `fields`.	`{ issues: [{ id, key, fields }], total }`
`getBacklogIssues`	Backlog issues of a `boardId`; optional `jql`.	`{ issues: [{ id, key, fields }], total }`

The Agile instructions require a fully-granular Jira Software OAuth setup — they do not work with the default classic scopes (see Prerequisites).

Attachments

Instruction	Description	Returns
`getAttachmentMeta`	Get an attachment’s metadata by `id`.	`{ id, filename, size, mimeType, content }`
`deleteAttachment`	Delete an attachment by `id`.	Empty (HTTP 204)

Returns shows the shape of the operation output (the underlying Jira REST resource). Attachment upload (add) is not available inline — binary multipart cannot transit the connector; upload via the Jira UI or REST API directly. To list an issue’s attachments, call getIssue with fields including attachment.

DSUL Examples

Search issues with JQL:

- JiraNext.searchJql:
    body:
      jql: "project = DEV AND status = 'In Progress' ORDER BY updated DESC"
      maxResults: 25
      fields:
        - summary
        - status
        - assignee
  output: results

Create an issue (ADF description):

- JiraNext.createIssue:
    body:
      fields:
        project:
          key: DEV
        issuetype:
          name: Task
        summary: '{{summary}}'
        description:
          type: doc
          version: 1
          content:
            - type: paragraph
              content:
                - type: text
                  text: '{{detail}}'
  output: newIssue

Discover create metadata, then transition an issue:

- JiraNext.getCreateMetaIssueTypes:
    projectIdOrKey: DEV
  output: types

- JiraNext.getTransitions:
    issueIdOrKey: '{{issueKey}}'
  output: transitions

- JiraNext.doTransition:
    issueIdOrKey: '{{issueKey}}'
    body:
      transition:
        id: '{{transitions.transitions[0].id}}'

Assign an issue to the connected user:

- JiraNext.getMyself: {}
  output: me

- JiraNext.assignIssue:
    issueIdOrKey: DEV-123
    body:
      accountId: '{{me.accountId}}'

Error Handling

HTTP code	Meaning
`400`	Bad request — invalid JQL, malformed body, or a field value Jira cannot parse.
`401`	Unauthorized — the Atlassian token is missing, expired or revoked. The user must reconnect (OAuth modes).
`403`	Forbidden — insufficient OAuth scope (e.g. a write with read-only scopes), or the account lacks permission on the project.
`404`	Not found — the issue, project, board, sprint or attachment id does not exist or is not visible to the account.
`422`	Unprocessable — a required field is missing or invalid; resolve field ids with `metadata` `fields` / `createmetaFields`.
`429`	Rate limit — back off and retry.
`500` / `503`	Atlassian service error — transient; retry shortly, no reconnection needed.

Common Issues

“This agent is not authorized to use this connector” — The calling agent is not in the allowlist. Open the configuration app → Authorized agents → tick this agent (or enable Allow all agents) and Save. “The calling agent could not be identified” — The MCP capability Scope does not declare agent_id, so Agent Factory never injects the agent identity. Set the Scope to context_id,agent_id,user_id on the capability, then allow the agent in the config app. “Jira is not connected for this user” — No per-user OAuth token. Open the configuration app (OAuth mode) and click Connect, or use the agent’s connect flow. “token refresh failed … must reconnect” — The stored refresh token was revoked or expired (Atlassian invalidated it). The connection is dropped automatically; the user must reconnect from the config app. “OAuth is not configured” — Neither a tenant Atlassian client nor the central platform client is available. Set the OAuth client ID/secret in the config app, or ask the platform maintainer to provision the central OAuth client. Agile call fails with “scope does not match” — The agile tool needs a fully-granular Jira Software OAuth app; it cannot run on a token that carries classic scopes. Either migrate the Atlassian app (and the connector Scopes field) to the fully-granular set, or avoid the agile operations. This is an Atlassian platform limitation (classic and granular Jira Software scopes are mutually exclusive on a token).

External Resources

Jira Cloud REST API v3

Official reference for the Jira platform REST API v3.

Jira Software (Agile) REST

Official reference for the Agile 1.0 boards / sprints / backlog API.

Atlassian OAuth 2.0 (3LO) scopes

Classic vs granular scopes reference for Jira OAuth 2.0 apps.

Tool Agents

Learn how Agent Factory agents consume MCP tools in Prisme.ai.

Issues & workflow

Projects & metadata

Per-user Atlassian OAuth

​Who is this for?

Agent builder

Platform admin

Workspace builder

​Prerequisites (Atlassian side)

​1. Configure the connector

​2. Declare the capability in AI Governance

​Agent builder

​Option A — Enable the shared capability from the catalog

​Option B — Run it from your own workspace (recommended)

​Brief the agent in its system prompt

​Available Tools

​Output Formats

​Tool Details

​search

​issues

​metadata

​agile

​users

​Workspace builder

​Installation

​Configuration

​Available Instructions

​Issues

​Search

​Projects

​Users

​Metadata

​Agile

​Attachments

​DSUL Examples

​Error Handling

​Common Issues

​External Resources

Jira Cloud REST API v3

Jira Software (Agile) REST

Atlassian OAuth 2.0 (3LO) scopes

Tool Agents

Who is this for?

Prerequisites (Atlassian side)

1. Configure the connector

2. Declare the capability in AI Governance

Agent builder

Option A — Enable the shared capability from the catalog

Option B — Run it from your own workspace (recommended)

Brief the agent in its system prompt

Available Tools

Output Formats

Tool Details

search

issues

metadata

agile

users

Workspace builder

Installation

Configuration

Available Instructions

Issues

Search

Projects

Users

Metadata

Agile

Attachments

DSUL Examples

Error Handling

Common Issues

External Resources