Skip to content

ATLASSIAN 2026-10-28 Tier 3

Read original ↗

Jira's depth on demand: designing an MCP server around jobs, not endpoints

Summary

Atlassian describes how it redesigned the Jira tools in the Atlassian (Rovo) MCP server — a service handling more than 15M tool calls every weekday and nearly 2M MAU (up 8× since March 2026). v1 was a deliberate MVP: 15 Jira tools that mapped almost 1:1 onto REST endpoints (creating an issue took four calls; transitionJiraIssue exposed the REST API's full historyMetadata object; descriptions like "Get transitions"). For v2 the team rejected the coverage-first path — auto-generating one tool per endpoint across Jira's ~725 REST operations — on three grounds: Jira operations rarely work alone, more tools mean more wrong picks and more schema in context, and most usage concentrates in a small slice of Jira. Instead they start from the job, not the API: 52 tools (calling 100+ distinct APIs) shaped around jobs to be done, grouped by intent into scope-gated groups (read/write/search on by default; delete/manage off), with enum action parameters, name-based resolution, descriptions that say when to use a tool, errors carrying a repairHint, JQL and view/expand escape hatches, and deferred loading — only 6 tools are always loaded; the other 46 are reached via discover and executed through risk-tiered executeRead / executeWrite / executeDestructive. Jira's workflow validators, conditions, and permissions still apply: the agent reads the workflow instead of guessing at it. An internal 84-case evaluation scored by final Jira state shows v2 completing 17 previously-impossible tasks, passing 57/62 shared cases (v1: 54), and halving failed tool calls per run (0.20 → 0.09).

Key takeaways

  1. Coverage-first vs. job-first is the central design decision. Jira's public REST API has ~725 endpoint/method pairs; one tool per endpoint could have been auto-generated from the spec. Atlassian rejected it because (a) jobs like closing an issue or running a sprint need several calls in the right order, (b) hundreds of schemas burn context and similar tools degrade selection accuracy, and (c) usage concentrates in a small slice of the API. The result: 52 tools over 100+ APIs — "the surface is much bigger than the tool list, but the list is shaped like the work." This is a canonical patterns/tool-surface-minimization instance with the explicit counter-option named. (Source: this page)
  2. Pick jobs from three inputs, and rank reads and writes separately. User requests (reinterpreted to the underlying goal), most-used Jira actions, and the team's own dogfooding. 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." (Source: this page)
  3. Server-side orchestration of multi-API jobs. manageJiraSprint reads the sprint, finds the tenant's story-point custom field via edit metadata, updates estimates, adds issues via the Agile API, and starts the sprint; getJiraBoardSprintData resolves board + active sprint by name, paginates sprint issues, and returns precomputed progress slices (assigned-to-me, at-risk). The agent stays on the outcome; the server owns call ordering and tenant-config lookups. (Source: this page)
  4. Schema-design tactics. Enum action parameters (create/addIssues/start/update/close) collapse lifecycles into one tool; humans' names ("the active sprint on the Payments board") replace IDs; custom fields accepted by name; descriptions state when to use a tool and point to the right neighbour; rejected writes return the faulting field, its allowedValues, and a repairHint so the agent self-corrects instead of looping; JQL passes through for compound searches; view = compact/evidence/full trades tokens for fidelity per call. (Source: this page)
  5. Governance is preserved, not bypassed. Closing an issue is deliberately two calls — listJiraIssueTransitions(expand: "transitions.fields") then transitionJiraIssue(... fields: {resolution: "Fixed"}) — one more round trip than a naive tracker, but validators, conditions, and post-functions still run and the agent sees which transitions are valid for this user, right now. (Source: this page)
  6. Layered authorization. Tools are grouped by intent: read_jira (27), write_jira (15), search_jira (1) on by default; delete_jira (3) and manage_jira (6) off by default, each behind its own scope a site admin must enable. Everything else runs with the signed-in user's permissions over OAuth 2.1 — "the agent can't do anything the user couldn't" (patterns/on-behalf-of-agent-authorization, concepts/least-privileged-access). On top, Atlassian Guard Data Security Policies can block MCP access to specific projects/spaces or to content classified Confidential/PII — a user may open a Restricted issue in the browser while their agent cannot (concepts/governed-agent-data-access). (Source: this page)
  7. Deferred loading with risk-tiered execution. v1 loaded all 32 tool definitions up front — ~60 KB of JSON schema, ~15k tokens before the user typed anything. v2 always loads 6 core tools (getJiraIssue, searchJiraIssuesUsingJql, createJiraIssue, editJiraIssue, transitionJiraIssue, addOrEditJiraIssueComment); the other 46 are found via discover and invoked through executeRead, executeWrite, or executeDestructive, making each call's risk tier explicit (concepts/progressive-capability-disclosure, concepts/ai-agent-guardrails). ?tools=all returns a flat catalog for gateways that need one. (Source: this page)
  8. Measured outcomes, judged by final state. Success is the resulting Jira state, not the agent's claim. October internal eval (84 cases): 17 tasks v1 couldn't attempt (sprints, versions, attachments, dashboards), 16 passing all three runs; 57/62 vs 54/62 on shared cases (no v1-only passes); failed calls 0.20 → 0.09 per run. Up to 25% fewer tokens than v1 for the same work; a separate architecture comparison found full up-front catalog loading used ~2.2× the cumulative input tokens of the curated deferred approach (concepts/context-window-as-token-budget). Remaining failures are kept as JTBD evals that drive improvement (e.g. "show me the backlog" answers differ from Jira's UI semantics). (Source: this page)
  9. Dogfooding loop. Because the server connects to Atlassian's own repos and Jira projects, engineers use it on their own work — including work on the server — so clumsy schemas surface quickly as extra lookups and retries. repairHint and name-based lookup came from that loop. A stale-feature-flag cleanup flow is triggered by a Jira transition (see sources/2026-09-24-atlassian-how-we-automated-feature-flag-cleanup-with-agentic-pipelines). (Source: this page)

Systems / concepts / patterns extracted

Operational numbers

Metric Value
Tool calls >15M every weekday
Atlassian MCP server MAU ~2M (8× since 2026-03-01)
Jira REST API surface ~725 endpoint/method pairs
v1 Jira tools 15 (plus 13 Confluence, a few shared; 32 loaded up front)
v1 up-front schema ~60 KB JSON ≈ 15k tokens
v2 Jira tools 52, calling 100+ distinct APIs
v2 always-loaded tools 6 (46 deferred)
Tool groups read 27 · write 15 · search 1 · delete 3 (off) · manage 6 (off)
Eval: new tasks 17 (16 pass all 3 runs)
Eval: shared cases v2 57/62, v1 54/62
Failed tool calls per run 0.20 → 0.09
Token savings vs v1 up to 25%
Full catalog vs deferred ~2.2× cumulative input tokens

Caveats

  • Tier-3, self-reported internal benchmarks; eval methodology, model(s) used, and token-measurement harness are not disclosed. "Up to 25%" is a best case.
  • The discover mechanism (search? category listing?) and the enforcement behind executeDestructive (confirmation? scope check?) are not described.
  • Server-side orchestration moves partial-failure semantics into the server (e.g. manageJiraSprint updating estimates then failing to start the sprint); rollback/idempotency behaviour is not discussed.
  • 15M calls/day and 2M MAU are product-level figures; no latency, error budget, or infrastructure topology is given.

Source

Last updated · 854 distilled / 2,448 read