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 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.
Issue management
Search with JQL, then create, read, update and delete issues — including custom fields once they are resolved by id.
Workflow operations
List and apply status transitions, add comments and attach files to move issues through their workflow.
Project & field discovery
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.Agent builder
You build agents in Agent Factory and want them to use Jira. → Agent builder tab.
Platform admin
You run the platform and want to know what to set up once for everyone. → Platform admin setup accordion below.
Workspace builder
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 Centerhttps://jira.yourcompany.com. - For Jira Cloud: an Atlassian account email and an API token, generated at Atlassian 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.
Platform admin (Governance) — one-time platform setup
Platform admin (Governance) — one-time platform setup
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)
Point it at the MCP endpoint
Set the capability’s MCP server URL to the connector’s MCP Endpoint (the workspace running the connector), and set its Scope to:The
agent_id in the scope is what lets the connector identify the calling agent.Make it available to agent builders
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.
- Agent builder (Agent Factory)
- Workspace builder (DSUL)
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).
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.Install and configure the connector in a workspace
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).
Add the MCP capability to your agent
In your agent, add a capability pointing at the workspace’s MCP Endpoint URL, and set its Scope to:The
agent_id lets the connector identify your agent. The credential is resolved from the workspace configuration server-side.Brief the agent in its system prompt
A short brief keeps the agent from guessing field ids or skipping discovery. Copy-pasteable starter: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 anoutputFormat argument that controls the MCP response shape:verbose(default) — human-readable text optimized for LLM consumptionstructured— machine-readable JSON instructuredContentboth— both the text and the structured content
Tool Details
searchJira
| 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
| Parameter | Required | Description |
|---|---|---|
issueKey | Yes | The issue key, e.g. DEV-123. |
createIssue
| 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
| Parameter | Required | Description |
|---|---|---|
query | No | Substring to match field names. |
customOnly | No | Restrict to custom fields when true. |
maxResults | No | Max fields to return. |
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
| 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
| 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. |
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 needsemail + 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
Jira Cloud REST API
Official API documentation for Jira Cloud.
Jira Data Center REST API
Official API documentation for Jira Data Center.
Atlassian API Tokens
Generate API tokens for Jira Cloud.
Tool Agents
Learn how Agent Factory agents consume MCP tools in Prisme.ai.