In this blog we’re going to walk you through our Jira MCP tool design journey, a critical part of Atlassian’s MCP AI capability, supporting more than 15M calls every weekday.
“MCP on Jira is the greatest advance since the airplane.”
– real quote from a happy Jira MCP customer
Ask an agent to close a Jira issue and the naive implementation is one request: set the status to Done, get a 200, report success.
In a real Jira tenant, that call may involve complex conditions and may well fail. The transition may have a validator that requires a resolution. It may have a condition that only lets QA close. It may fire a post-function that notifies compliance. The agent knows none of this, so it takes a 400 and retries, or takes a 403 and tells you Jira is broken.
None of that is an accident. Workflows, permission schemes, and audit history are why Jira is a critical part of large organizations, and Atlassian’s cloud products are independently audited against standards such as SOC 2 and ISO 27001 (Atlassian Trust Center). The same configurability that lets a 10-person team and a regulated bank both run on Jira has always been part of its core value.
But sometimes that configurability and depth isn’t what you want. You want to start a project on Monday with a simple To Do → Doing → Done board, or have an agent triage a backlog without first learning your admin model.
That’s what we built the Jira tools in the Atlassian MCP server to do. The depth is there when you need it and stays out of the way when you don’t. This post covers how we got there.
The idea here is simple: start from the job, not the API. People don’t want to call endpoints. They want to close an issue, start a sprint, or find out what to focus on today. Jira can do each of those, but every one takes several API calls in the right order, shaped by your tenant’s configuration. So we designed our tools around those jobs to be done, and let the server handle the coordination, so the agent can concentrate on the outcome.
But that’s not where we started. Our first version took the opposite approach, and choosing between the two led to one of the bigger debates we’ve had on the team.
v1 was an MVP, and then we debated our v2 approach
Our first set of Jira tools on Atlassian MCP was a deliberate MVP. MCP itself was emerging, and we wanted something in customers’ hands quickly so we could learn what they needed and improve it fast. v1 shipped with 15 Jira tools (alongside 13 for Confluence and a few shared ones) covering the base use cases: creating, editing, and transitioning issues, comments, worklogs, links, and JQL search. There was nothing for boards, sprints, versions, or attachments. The tools mapped almost directly onto the underlying REST APIs, and you can see it in the definitions. Creating an issue took four calls: getVisibleJiraProjects, getJiraProjectIssueTypesMetadata, getJiraIssueTypeMetaWithFields, then createJiraIssue. transitionJiraIssue accepted the REST API’s full historyMetadata object, with nested actor, generator, and cause records that no agent needs. And most descriptions were a few words long, such as “Get transitions” and “Get projects”.
As we looked ahead to v2, we debated the best strategy to move forwards with.
Jira’s public REST API documents roughly 725 operations (counting each endpoint and HTTP method pair separately). Our product teams wanted to grow coverage fast, and the easy path was one tool per endpoint; we could have automated that relatively quickly from our API spec.
We looked at how others had approached it. The range ran from extreme coverage, where one MCP server exposes a huge share of a very large API, to deliberately narrow servers that expose a few tools for limited use-cases. Both ends of the spectrum have a case.
As we sparred internally, we kept coming back to three problems with the coverage-first approach:
- Jira operations rarely work alone. Closing an issue, running a sprint, or cutting a release takes several calls in the right order. A tool that maps to one endpoint rarely gets the user to the outcome they wanted.
- More tools means more wrong picks. Hundreds of schemas use up context before the agent has done any reasoning, and similar tools make it harder for the agent to choose correctly. We saw this even with the small set we launched. There’s only so much you can explain to an agent about what to do, and even a well-chosen tool might not deliver the result the user was after.
- Most people use a small slice of Jira. After 20+ years of improvements to Jira, most activity concentrates in a much smaller set of actions and APIs.
So we pushed for focus: target the jobs people actually do, and prioritize them alongside the most-used Jira capabilities. This was a deliberate choice over broad API coverage. We built tools that know how to get work done and know how to coordinate Jira APIs effectively to do so.
Since then, usage has grown steadily, tool failure rates have dropped markedly, and our internal benchmarking is helping us better understand the impact on context and cost, and helping us identify areas for improvement, while ensuring that our primary success metric – did I achieve the outcome I wanted? – continues to improve.
The result is 52 Jira tools (at time of writing) that, between them, call more than 100 distinct APIs. The surface is much bigger than the tool list, but the list is shaped like the work.
To help admins and users choose how they want to work, the tools are grouped by intent:
| Group | Tools | On by default |
|---|---|---|
read_jira | 27 | yes |
write_jira | 15 | yes |
search_jira | 1 | yes |
delete_jira | 3 | no |
manage_jira | 6 | no |
The last two rows matter to anyone who has to sign off on this. Deleting issues, comments, and attachments, and administering projects, workflows, and screens, each sit behind their own scope. A site admin decides whether an agent can do those things at all. The other groups follow the signed-in user’s existing permissions over OAuth 2.1. The agent can’t do anything the user couldn’t.
Permissions are only half of the story. Organizations on Atlassian Guard can also apply Data Security Policies (DSPs) to MCP traffic, the same way they already control exports, attachment downloads, public links, and app access. An admin can block Atlassian MCP server access to selected Jira projects or spaces, or only to content with a sensitive classification such as Confidential or PII. A user might still open a Restricted issue in the browser, but an agent working for them can’t read it.
How we picked the jobs
We didn’t start from the API. We started with a curated list of jobs to be done, built from three inputs:
- What users asked for. Requests from customers and from teams building on the server. We tried to look past the literal ask to understand what the user was trying to achieve. Sometimes we found the best solution wasn’t necessarily the one that was originally proposed.
- What people already do most. We looked at the most commonly used actions and workflows in Jira, and ranked reads and writes separately. Reads outnumber writes by orders of magnitude, so a single combined ranking gives you an agent that can summarize a sprint but can’t assign a ticket.
- What we needed ourselves. We’re software developers who live in Jira, and that informed priorities and implementation details. When a tool call was awkward for us, it went back on the list.
Each job then got implemented as a small number of tools, even when that means the server coordinates several APIs behind it. Here are some of those jobs:
Plan and start a sprint.
“Start Sprint 42 with these two issues, and estimate PROJ-1 at 8 points.”
getJiraBoardSprintData resolves the board and sprint; manageJiraSprint reads the sprint, looks up the site’s story-point field via issue edit metadata, updates the estimate, adds the issues through the Agile API and starts the sprint. That’s two tools coordinating board, sprint and issue APIs rather than making the agent orchestrate each request.
Wrap up a sprint.
“Close the done sub-tasks, carry the rest into the next sprint, and post the carryover list on the epic.”
The agent can use getJiraBoardSprintData and searchJiraIssuesUsingJql to find the work, transitionJiraIssue for each change, then addOrEditJiraIssueComment for the summary. Behind those tools, Jira checks available workflow transitions, applies them through the issue API, and uses the Agile API to move issues to a sprint or backlog; the agent stays focused on the outcome across multiple issues.
Find out what to focus on today.
“What should I focus on today?”
A single getJiraBoardSprintData call can resolve the project’s board, find its active sprint and fetch the sprint issues through the Agile APIs, including further pages when needed. The server returns progress slices such as assigned-to-me and at-risk, so the agent can answer without asking the user for a board or sprint ID.
How we designed the tools around the jobs
Intent over endpoints. Agents choose MCP tools based on the user’s intent, not the API endpoint behind them. Defining each tool around a job to be done makes the right choice easier to recognise and has improved how reliably agents select the right tool.
Enums to reduce tool sprawl. manageJiraSprint takes an action of create, addIssues, start, update, or close. The model already understands the lifecycle, so we don’t spend schema budget on five separate tools. The same pattern covers project versions and watchers.
Operations that match your intent. Humans say “the active sprint on the Payments board,” not sprintId=4417. getJiraBoardSprintData resolves a board and sprint by name and defaults to the active sprint. It returns the issues with progress slices such as assigned-to-me and at-risk, so the agent doesn’t have to compute them. createJiraIssue accepts custom fields by name and an assignToSprint of "active". manageJiraSprint takes a storyPoints map and works out which custom field holds estimates for each issue.
Descriptions that say when to use a tool, not just what it does. v1 described getTransitionsForJiraIssue as “Get transitions.” Its v2 replacement, listJiraIssueTransitions, says it lists the transitions this issue can take right now for the calling user, and that when the user names a target status the agent should match the status a transition leads to, not the transition’s name. Most v2 descriptions also point to the right neighbour, such as “for the active sprint plus its issues and progress in one call, use getJiraBoardSprintData.”
Errors that tell the agent what to do next. A rejected create names the field at fault, lists its allowedValues where known, and carries a repairHint. The agent corrects itself instead of looping.
Escape hatches where the model needs them. JQL passes straight through for compound searches, which keeps date windows and custom-field logic server-side. Where a job needs more detail, an expand or a view of compact, evidence, or full trades tokens for fidelity per call.
Governance as part of the answer. Closing an issue is still two calls:
listJiraIssueTransitions(issueIdOrKey: "PROJ-1234", expand: "transitions.fields")
→ transitions valid for this issue, for this user, right now, and the fields each one requires
transitionJiraIssue(issueIdOrKey: "PROJ-1234", transitionId: "31", fields: { resolution: "Fixed" })That’s one more round trip than a simple tracker. In exchange, the agent reads the workflow instead of guessing at it, and your validators and conditions still apply. Jira’s depth is working for the agent here, not against it.
Some tools do the coordination themselves. transitionJiraIssue can change status and move the issue into a sprint or back to the backlog in one call, because an engineer would describe that as one job.
Using the MCP to improve the MCP
Because the server connects to our own repositories and Jira projects, we use it to drive our own work, including work on the server. An agent can pick up a ticket, read the code, and prepare a change for an engineer to review. Where the tools are clumsy, it shows up quickly in our own sessions: extra lookups, retries, schemas that make the model guess. We fix those, and the next session is a little better. The loop is informed by engineers who use the tools daily, which is why things like repairHint errors and name-based lookups exist.
Internal teams also run narrower workflows on it. In one, moving a stale-feature-flag cleanup ticket in Jira triggers an agent with repo-specific context to open a removal PR, and the Jira transition decides when the agent runs.
Keeping context small
v1 loaded all 32 tool definitions up front, about 60 KB of JSON schema (roughly 15k tokens, estimated at 4 characters per token) before the user typed anything. v2 loads six tools, which are always available: getJiraIssue, searchJiraIssuesUsingJql, createJiraIssue, editJiraIssue, transitionJiraIssue, and addOrEditJiraIssueComment. The other 46 are deferred, found through discover and run through executeRead, executeWrite, or executeDestructive, so the risk tier of each call is explicit. If your MCP gateway needs a flat tool list, <https://mcp.atlassian.com/v2/mcp?tools=all> returns the full catalog.
Because this is one server across the whole Teamwork Collection, a single session can cross them. In our GA example, an agent turned a Loom video and a Slack thread into a Confluence plan, a seeded Jira project, and a Goal linked to its Projects. The links land in the Teamwork Graph, where you can query them, instead of as URLs pasted into descriptions.
Hear more from our CEO on how we are working to transform and support AI-native ways of working: Atlassian Team ’26: Meet the AI-Native Organization – Inside Atlassian
Does it work?
We judge outcomes by final Jira state, not by what the agent says. If it reports creating an issue and none exists, that’s clearly a failure.
It gets more work done. In an internal October evaluation of 84 Jira cases:
- v2 completed 17 tasks that v1 had no tool for, including sprints, versions, attachments, and dashboards. 16 passed all three runs.
- On the 62 cases both versions can attempt, v2 passed 57 and v1 passed 54. v2 passed three that v1 didn’t. v1 passed none that v2 failed.
- Failed tool calls fell from 0.20 to 0.09 per run, so agents spend fewer turns recovering from errors.
Our customers are seeing that value in real time–Atlassian MCP Server now has nearly 2M MAU, up 8x since 1 Mar 2026.
It’s leaner where the catalog is big. In internal benchmarking, Atlassian MCP v2 saves up to 25% tokens than v1 to do the same Jira work. In a separate architecture comparison we ran, loading the full tool catalog up front used roughly 2.2× the cumulative input tokens of our curated, deferred approach. That second comparison is the one that matters for the design argument. A tool list that grows with the API surface gets more expensive for everyone, whether or not they use the extra tools.
What about the failures? So you noticed above that 5 of our internal tests still failed on the v2 tools? This is actually by design. We’ve developed a set of internal evals that help us understand the sorts of tasks our customers expect their agent to solve–they aren’t just there to pat us on the back when we get it right. Instead, we continue to use these JTBD-focused evals to identify opportunities to make thoughtful tool improvements.
By way of example, one of the tests that fail on both our v1 and v2 toolset asks the agent to;
“Show me the backlog for the mobile team’s board.”
The problem we identified here is not that your agent can’t answer this question, it’s that the answer it lands on is a bit different from the way Jira’s UI answers. We’re still sparring on the best path forwards here.
Try it
Add the server to your client and sign in. In Claude Code, for example:
claude mcp add --transport http atlassian https://mcp.atlassian.com/v2/mcpThen run /mcp to authenticate. Other clients are covered in the setup guide, and the tool schemas are public.
Start with a test project and say what you want, the way you’d say it to a teammate:
- “What should I focus on today?”
- “Start Sprint 42 with these two issues, and estimate PROJ-1 at 8 points.”
- “Close the done sub-tasks, carry the rest into the next sprint, and post the carryover list on the epic.”
- “Mark PROJ-123 done.” Watch what happens if your workflow requires a resolution.
Jira’s complexity wasn’t the problem to solve. The problem is when that complexity gets in your way. Our MCP tools are designed around one goal – enabling Jira to support your work and keep the complexity out of the way until you need it. When you do need it, Jira will still be there, and with our MCP to help, the way you work won’t need to change.
If you hit a job we should have covered, let us know. Chances are high, it’s a job we do as well.
