Jira MCP is not a single product — it's a pattern. An MCP server sits between your AI coding agent and the Jira REST API, exposing a fixed set of callable tools (search issues, create issue, transition status, and so on) so the model doesn't have to hand-roll HTTP requests or guess endpoint shapes. Two implementations dominate real deployments today: the community-maintained sooperset/mcp-atlassian (API-token auth, self-hosted, ~2k GitHub stars, actively maintained through 2025), and Atlassian's own Remote MCP Server at mcp.atlassian.com (OAuth 2.1, no token management, but you're trusting Atlassian's hosted infra and it currently bundles Jira with Confluence rather than letting you scope to Jira alone). This module focuses on the API-token path because it's what most teams running Claude Code, Cursor, Gemini CLI, or OpenCode actually wire up first — it's self-hosted, auditable, and works identically across every client.
If you've used the Jira REST API directly, nothing here will surprise you. MCP is a translation layer, not new functionality. The ceiling on what your AI agent can do is exactly the ceiling of the Jira Cloud REST API v3 (or Server/Data Center v2), plus whatever subset of endpoints the MCP server author decided to wrap. That subset matters a lot in practice — as of mcp-atlassian v0.11.x, Advanced Roadmaps/Plans, Jira Service Management queues, and some admin-only endpoints are not exposed at all.
Core Jira MCP Tools: Issues, Sprints, Boards, and JQL Search
mcp-atlassian exposes roughly 30 Jira tools (plus a parallel set for Confluence if you enable it). The ones you'll use daily fall into four buckets:
Issue read/write
- jira_get_issue — fetch a single issue by key (PROJ-123), with optional fields and expand params to control payload size
- jira_search — run a raw JQL query and get back paginated results
- jira_create_issue — create with project key, issue type, summary, description, and arbitrary custom fields as JSON
- jira_update_issue — patch fields on an existing issue
- jira_batch_create_issues — create multiple issues in one call, useful for backlog seeding
- jira_delete_issue — exists, but most teams disable it (see the scope-limiting section below)
Workflow and collaboration
- jira_get_transitions — list the valid next statuses for an issue (Jira workflows are state machines; you can't jump straight from "To Do" to "Done" if there's a required "In Review" gate)
- jira_transition_issue — move an issue through its workflow
- jira_add_comment, jira_add_worklog — comment and log time
- jira_create_issue_link, jira_link_to_epic, jira_remove_issue_link — relate issues (blocks, relates to, epic link)
Agile / sprint tools
- jira_get_agile_boards — list boards visible to the account
- jira_get_board_issues, jira_get_sprints_from_board, jira_get_sprint_issues
- jira_create_sprint, jira_update_sprint — only works against company-managed (classic) Scrum boards; team-managed (next-gen) projects use a different internal API that mcp-atlassian does not fully support as of this writing, so sprint mutation tools silently fail or 404 there
Metadata
- jira_search_fields — resolves human field names to the customfield_10XXX IDs Jira uses internally, which you'll need constantly once you touch Story Points, Epic Link, or any custom field
jira_search(jql="project = PROJ AND sprint in openSprints() AND assignee = currentUser()")
jira_get_sprint_issues(board_id=42, sprint_id=117)
jira_transition_issue(issue_key="PROJ-451", transition_id="31")
JQL is the real power tool here. Every "smart" query your AI agent runs — "what's blocking the release," "show me stale bugs" — ultimately compiles down to a JQL string passed to jira_search. Knowing JQL yourself is non-negotiable if you want to sanity-check what the agent is doing.
project = PROJ AND issuetype = Bug AND priority in (Highest, High)
AND status not in (Done, Closed) ORDER BY created ASC
Tips
- Runjira_search_fieldsonce per project and paste the custom-field-ID mapping into your agent's context (aJIRA_FIELDS.mdfile works well) — it saves the model from guessingcustomfield_10014vscustomfield_10016for Epic Link.
- Sprint mutation tools only work reliably on company-managed Scrum boards — check your board type before promising a client "AI-managed sprints" on a team-managed project.
- Capjira_searchresult size explicitly (maxResults) — a JQL query with no bound can return hundreds of issues and blow through the model's context window in one tool call.
Jira MCP Authentication: API Token Setup and Project Configuration
Jira Cloud auth for mcp-atlassian is basic auth: your Atlassian account email plus an API token, base64-encoded under the hood by the server. Server/Data Center instances use a Personal Access Token (PAT) instead — no email required, just the token as a bearer credential.
Step 1 — generate the token (Cloud):
- Go to
https://id.atlassian.com/manage-profile/security/api-tokens - Click "Create API token," name it something traceable (
mcp-claude-code-2026), copy it immediately — Atlassian won't show it again - Optionally use a scoped token (limited to specific APIs) instead of a classic token — scoped tokens are newer and let you restrict to
read:jira-workandwrite:jira-workwithout granting account-wide access
Step 2 — verify the token before wiring up MCP:
curl -s -u "you@company.com:$JIRA_API_TOKEN" \
-H "Accept: application/json" \
"https://your-domain.atlassian.net/rest/api/3/myself" | jq '.displayName, .accountId'
If that returns your name and account ID, the credential works. Debugging MCP connection failures is much harder than debugging a plain curl call — always validate at this layer first.
Step 3 — set environment variables:
export JIRA_URL="https://your-domain.atlassian.net"
export JIRA_USERNAME="you@company.com"
export JIRA_API_TOKEN="ATATT3xFfGF0..."
export JIRA_PROJECTS_FILTER="PROJ,INFRA"
JIRA_PROJECTS_FILTER is the single most important variable for team use — it restricts every tool call to the listed project keys, so a JQL query like project = SECRET-PROJECT simply returns nothing even if the credential technically has access. Set it even when you think you don't need it; scope creep in shared repos is real.
For Server/Data Center, swap the last two lines for:
export JIRA_URL="https://jira.internal.company.com"
export JIRA_PERSONAL_TOKEN="your-pat-here"
Tips
- Never putJIRA_API_TOKENdirectly in a committed.mcp.jsonoropencode.json— reference an environment variable and keep the actual value in.env,direnv, or your OS keychain.
- Prefer a scoped API token over a classic one when your Atlassian org supports it (available on most Cloud sites since 2024) — classic tokens inherit your full account permissions.
- Rotate the token every 90 days and give it a name that includes the issuing date; orphaned tokens named "token1" are how security audits go sideways.
What AI Can and Cannot Do with Jira MCP
What works well in practice:
- Reading and summarizing issues, sprints, and boards — the agent is genuinely good at turning a wall of ticket text into a coherent status report
- Drafting bug reports and acceptance criteria from a stack trace, log snippet, or vague Slack message
- Running exploratory JQL — "find every Bug tagged regression opened in the last 14 days" — faster than you'd type it into Jira's UI
- Transitioning issues and adding comments as part of a scripted workflow (e.g., "when this PR merges, move the linked issue to Done and comment the commit SHA")
- Bulk-tagging or bulk-labeling issues that match a JQL filter, via jira_batch_create_issues for creation or repeated jira_update_issue calls for edits
Where it breaks down or needs a human:
- Custom field validation. Jira lets admins mark fields required-on-transition. The REST API error for a missing required field is often a generic 400 with a field ID, not a name — the agent will report "update failed" without knowing why unless you've mapped field IDs in advance.
- Workflow permission errors. If your account lacks the "Transition Issues" permission in a given project, the failure looks identical to a broken workflow ID. The agent can't distinguish "you're not allowed" from "that's not a valid transition" without you checking Jira's permission scheme directly.
- Priority and severity judgment calls. The agent can suggest a priority based on the bug description, but it doesn't know your team's SLA commitments or which customer is complaining. Treat AI-assigned priority as a first draft, not a final decision — see Module 8's real-world workflow topic for how to structure human review into that step.
- Advanced Roadmaps / Plans, JSM queues, portfolio-level dependencies — not exposed by mcp-atlassian at all as of this writing. Don't promise stakeholders AI-driven roadmap management on top of this stack.
- Attachments. jira_download_attachments pulls files to local disk, but the model doesn't automatically read image or PDF content from them — you still need a separate step (vision model call, OCR) to extract information from a screenshot attached to a bug report.
Tips
- Treat any AI-suggested priority, estimate, or sprint assignment as a recommendation with a visible "AI-suggested" label or comment, never a silent write — reviewers need to know what was automated.
- When a write operation fails, ask the agent to runjira_get_transitionsorjira_search_fieldsbefore retrying — most "it just failed" reports are missing-context problems, not MCP bugs.
- Keep a short list of project-specific workflow quirks (required fields on transition, unusual permission schemes) in your agent's system context; it eliminates a whole class of confusing failures.
Limiting Jira MCP Scope for Security and Safe Automation
Jira MCP servers typically run with whatever permissions the underlying account has — which, for a personal API token, can mean full read/write across every project you can see. That's too broad for anything beyond solo experimentation.
Concrete scope controls in mcp-atlassian:
export JIRA_PROJECTS_FILTER="PROJ,INFRA" # restrict to named projects
export READ_ONLY_MODE="true" # disable all write tools globally
export ENABLED_TOOLS="jira_get_issue,jira_search,jira_get_agile_boards,jira_get_sprint_issues"
ENABLED_TOOLS is the sharpest instrument — an explicit allowlist means jira_delete_issue and jira_batch_create_issues simply don't exist from the model's perspective, regardless of what the credential could technically do.
Account-level practices:
- Use a dedicated Jira service account (ai-agent@company.com) rather than a real engineer's personal token — permissions, audit trail, and revocation are all cleaner
- Scope that service account's project permissions in Jira's permission schemes to exactly the projects it needs, not "Administer Jira"
- Check Jira's audit log (Settings → System → Audit log on Cloud) periodically for actions taken by the service account — it's the same log a human's suspicious activity would show up in
- For anything destructive (bulk transitions, bulk delete), require the agent to print the JQL and the count of affected issues before executing, and pause for confirmation — most CLI agents support this as a manual approval step
-- Always run a dry-run search before a bulk write:
project = PROJ AND labels = "stale-2024" AND status != Done
Tips
- Default new Jira MCP setups toREAD_ONLY_MODE=truefor the first week of use — flip it off only after you trust the prompts you're sending and the JQL the agent constructs.
- Never enablejira_delete_issuein a shared or CI-triggered agent config; deletions in Jira are not soft — recovering a deleted issue requires a support ticket to Atlassian.
- Log every AI-initiated write (comment, transition, field update) with a consistent marker like[AI-agent]in the comment body, so a human reviewing history later can tell automation from manual edits.
Tips
Jira MCP gives your AI agent the same reach a junior team member with API access would have — genuinely useful for the repetitive parts of sprint hygiene, but only as trustworthy as the scope you grant it and the JQL it's allowed to run unsupervised.
Tips
- Start every new Jira MCP integration inREAD_ONLY_MODE, on a single test project, before touching anything your team depends on.
- Keep a living reference of your project's custom field IDs and workflow transition IDs — most "the AI got Jira wrong" complaints trace back to missing that context, not a model failure.
- Prefer a scoped service account over a personal API token the moment more than one person or one automated job touches the integration.