Skip to main content
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.
Jira The Jira connector exposes Atlassian 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.

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 Center https://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.
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)

1

Open AI Governance > Capabilities

Create (or edit) the Jira capability.
2

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:
context_id,agent_id,user_id
The agent_id in the scope is what lets the connector identify the calling agent.
3

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.
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.
1

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).
2

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:
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.
3

Brief the agent

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:
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

ToolDescription
searchJiraSearch issues using JQL
getIssueGet issue details by key
createIssueCreate a new issue
updateIssueUpdate an existing issue
deleteIssueDelete an issue

Field Discovery

ToolDescription
listFieldsList or search Jira fields, including custom fields
listCreateIssueTypesList issue types available when creating issues in a project
getCreateIssueFieldsGet fields available on the create screen for a project and issue type

Workflow Operations

ToolDescription
getTransitionsGet available status transitions
transitionIssueChange issue status
addCommentAdd a comment to an issue
addAttachmentAdd an attachment to an issue

Project Operations

ToolDescription
listProjectsList accessible projects
getProjectGet project details

Configuration

ToolDescription
configureJiraStore 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

{
  "name": "searchJira",
  "arguments": {
    "jql": "project = DEV AND status = \"In Progress\"",
    "maxResults": 10
  }
}
ParameterRequiredDescription
jqlYesJQL query string (project, status, assignee, labels, text search, …).
maxResultsNoMax results per page (default 50).
nextPageTokenNoCursor for the next page of results.
fieldsNoComma-separated list of fields to return.

getIssue

{
  "name": "getIssue",
  "arguments": {
    "issueKey": "DEV-123"
  }
}
ParameterRequiredDescription
issueKeyYesThe issue key, e.g. DEV-123.

createIssue

{
  "name": "createIssue",
  "arguments": {
    "projectKey": "DEV",
    "issueType": "Task",
    "summary": "Implement new feature",
    "description": "Detailed description here",
    "priority": "High",
    "fields": {
      "customfield_10016": 8
    }
  }
}
ParameterRequiredDescription
projectKeyYesTarget project key.
issueTypeYesIssue type name (e.g. Task, Bug, Story).
summaryYesIssue summary / title.
descriptionNoIssue description.
priorityNoPriority name (e.g. High).
fieldsNoMap of additional fields by id, e.g. customfield_10016. Resolve custom-field ids with listFields first.

listFields

{
  "name": "listFields",
  "arguments": {
    "query": "testPrismeField",
    "customOnly": true,
    "maxResults": 50
  }
}
ParameterRequiredDescription
queryNoSubstring to match field names.
customOnlyNoRestrict to custom fields when true.
maxResultsNoMax 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

{
  "name": "transitionIssue",
  "arguments": {
    "issueKey": "DEV-123",
    "transitionId": "31",
    "comment": "Moving to In Progress"
  }
}
ParameterRequiredDescription
issueKeyYesThe issue to transition.
transitionIdYesThe transition id from getTransitions.
commentNoOptional comment added with the transition.

configureJira

{
  "name": "configureJira",
  "arguments": {
    "baseUrl": "https://yoursite.atlassian.net",
    "type": "cloud",
    "email": "you@example.com",
    "apiToken": "your-api-token"
  }
}
ParameterRequiredDescription
baseUrlYesJira base URL.
typeYescloud or datacenter.
emailFor CloudAtlassian account email.
apiTokenFor CloudAtlassian API token.
personalAccessTokenFor Data CenterPAT 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.

Error Handling

HTTP StatusErrorSolution
401UnauthorizedVerify the API token (Cloud) or PAT (Data Center) and the account email.
403ForbiddenCheck the account’s permissions on the target Jira project.
404Not FoundVerify the issue key, project key, or transition id exists and is visible to the account.
422UnprocessableA field value is invalid or a required field is missing — resolve field ids with listFields / getCreateIssueFields.
429Rate LimitedWait and retry.
500Server errorTransient 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

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.