Jira MCP: how to connect AI agents to Jira through Model Context Protocol

By the end of this guide, you'll have an AI agent that can read, search, and update Jira issues through the Model Context Protocol (MCP). We'll use Atlassian's official remote MCP server, wire OAuth, connect it to Claude Desktop, and cover the gotchas that break most first attempts.

Prerequisites: an Atlassian Cloud site with Jira (this doesn't work on Data Center or Server), site-admin rights or the ability to get a site admin to approve the connection, and one MCP-capable client — Claude Desktop, Cursor, or VS Code with an MCP extension. Time required: about 30 minutes for a clean setup, longer if OAuth consent gets stuck in review.

A quick note on scope. Atlassian ships a hosted remote MCP server that covers Jira and Confluence in one endpoint. You don't build the server yourself — you connect to theirs. That's the setup this guide walks through. If you want to build your own MCP server against Jira's REST API, that's a different post — start here once you understand the hosted option.

Step 1 — Confirm your Atlassian site is eligible

Atlassian's remote MCP server only works with Atlassian Cloud. Data Center and Server sites aren't supported and won't be. If you're not sure which you're on, check the URL: yoursite.atlassian.net is Cloud. Anything else is not.

Second check: your site needs Rovo enabled, and the Remote MCP server toggle switched on for the products you want to expose. Rovo is enabled by a site admin under Atlassian Admin → Settings → Rovo. Once that's on, the Remote MCP server itself is toggled per product under Settings → Products (one toggle for Jira, one for Confluence). Both need to be in place before the endpoint will accept your OAuth request.

Expected result: you can log in to yoursite.atlassian.net, you see Jira in the app switcher, Rovo is enabled, and the Remote MCP server is on for Jira.

Step 2 — Install an MCP-capable client

Pick one client for this walkthrough. Claude Desktop is the simplest for a first setup because Anthropic documents remote MCP servers well and the setup flow is straightforward.

Download Claude Desktop from claude.ai/download. Open it and sign in. Claude Desktop now supports remote MCP servers natively via Custom Connectors, so for most users you won't need to edit a config file at all — you can add the Atlassian server directly from the UI. We'll cover both paths below.

Expected result: Claude Desktop is installed and you've signed in.

Step 3 — Add the Jira MCP server to your client

Option A — Custom Connectors (recommended). In Claude Desktop, go to Settings → Connectors → Add custom connector. Give it a name (e.g. Atlassian) and paste the remote MCP URL:

https://mcp.atlassian.com/v1/mcp/authv2

Claude Desktop will handle the OAuth flow directly. This is the current recommended path for third-party remote MCP servers and doesn't require any local shim.

Option B — mcp-remote shim (for stdio-only clients). If you're on a client that doesn't yet support remote MCP natively, you can bridge stdio to the remote endpoint with the mcp-remote shim. Open the client's config file — for Claude Desktop that's ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows — and add:

{
  "mcpServers": {
    "atlassian": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.atlassian.com/v1/mcp/authv2"
      ]
    }
  }
}

Note: the older https://mcp.atlassian.com/v1/sse endpoint is legacy SSE transport and shouldn't be used for new setups — the current server uses Streamable HTTP.

Save the file (if you used Option B) and restart the client.

Expected result: the client launches without errors and shows the Atlassian connector as pending OAuth. If the config JSON is malformed, Claude Desktop will silently skip the server — validate the JSON before saving.

Step 4 — Complete the OAuth consent flow

On first connection, Claude Desktop will open a browser tab pointing at Atlassian's OAuth consent screen. Sign in with the Atlassian account you use for Jira, pick the site you want the agent to reach, and approve the requested scopes.

The scopes cover a broad tool surface: reading issues, projects, and users; creating and editing issues; adding comments; transitioning issues through workflow states; logging work; and — if Confluence is enabled — creating and updating pages. Understand the full blast radius before approving, not just the read scopes.

If your organisation requires admin approval for third-party OAuth apps, the consent screen will show a message saying an admin needs to approve first. In that case, the request sits in the admin queue at Atlassian Admin → Settings → Connected apps until someone acts on it. This is the step that most often stalls a Jira MCP setup — factor it into your timeline.

Expected result: the browser tab shows a success page, and Claude Desktop's connector indicator shows atlassian as connected.

Step 5 — Verify the tools are available

In Claude Desktop, open a new chat and type /. You should see the tools the Atlassian server exposes, prefixed with something like atlassian: — getJiraIssue, searchJiraIssuesUsingJql, createJiraIssue, addCommentToJiraIssue, transitionJiraIssue, and a similar set for Confluence if your site has it.

Run a smoke test. Ask: "Search my Jira for issues assigned to me and updated in the last week." Claude should call searchJiraIssuesUsingJql with a JQL query like assignee = currentUser() AND updated >= -7d and return the results.

If tools don't appear at all, the OAuth flow probably didn't complete — check the connected apps page in Atlassian settings to confirm the app is present. If tools appear but calls fail with a 403, the account you signed in with doesn't have permission on the project you're querying. Jira permissions carry through the MCP server; there's no service-account backdoor.

Expected result: the smoke-test query returns real issue data from your Jira site.

Step 6 — Scope the agent's write access

Read access is the low-risk starting point. Write access — creating issues, editing fields, adding comments, transitioning workflow states, logging work — deserves more thought before you turn it loose.

The MCP server executes every call as the authenticated user. That's the right default: audit trails are honest, permissions are respected, and you don't need to hand out a shared service account. But it also means an agent acting on your behalf can do anything you can do. If you're a project admin, the agent is a project admin.

Three practical mitigations. First, use a dedicated Atlassian account for agent work if your organisation allows it — one with least-privilege access to only the projects the agent needs. Second, keep the agent scoped to a specific project in your prompts ("Only work in the SUPPORT project") — this doesn't enforce a boundary, but it reduces accidental cross-project writes. Third, review the tool calls before approving them; Claude Desktop surfaces each call for approval, though the exact behaviour depends on your client's approval settings (auto-approve toggles, per-tool allowlists) — check what's configured before assuming every call will prompt you.

For teams building production agents on Jira rather than exploring in Claude Desktop, the boundary needs to move into the runtime. See zero trust for AI agents for how delegated identity at the tool call actually holds up.

Expected result: you have a clear model of which account the agent uses, and which projects it can touch.

Step 7 — Test the workflow that matters to you

Run the real thing, not a demo. Pick one workflow you actually do in Jira — triage new bugs, summarise a sprint, roll up open blockers — and ask the agent to do it end to end.

A good triage test: "Look at all bugs created in the SUPPORT project in the last 24 hours. For each, tell me the reporter, the severity if labelled, and whether it looks like a duplicate of an open issue. Suggest a priority."

Watch what breaks. Common failure modes: the agent fetches issues one at a time instead of in a JQL batch (slow and hits rate limits), it summarises the first page and ignores pagination (missing data), or it invents an issue key that doesn't exist (hallucination on a lookup miss). These aren't MCP problems — they're tool-selection and schema problems that show up in every agent project.

Expected result: the workflow runs, and you have a concrete list of what needs to improve before you'd trust it unattended.

Common pitfalls

OAuth admin approval blocks the whole setup. If your Atlassian tenant requires admin approval for third-party OAuth apps, nothing works until an admin acts on the request. Ask up front rather than discovering it at step 4.

The mcp-remote shim caches OAuth tokens per user profile. If you switch Atlassian accounts, delete the cache at ~/.mcp-auth/ (macOS/Linux) or the equivalent on Windows, then reconnect.

Rate limits are per tenant and per app, not per agent. Jira Cloud enforces a points-based hourly quota per app (shared across tenants), plus burst limits per tenant per endpoint, plus per-issue write limits. None of them scale with the number of users you add. If an agent fans out parallel JQL searches you'll hit the burst limit and get 429s. Slow the agent down, batch queries with JQL, or use pagination properly — see Atlassian's rate-limiting docs and our note on parallel tool calls for how to size concurrency safely.

Tool responses can blow the context window. searchJiraIssuesUsingJql on a large project returns a lot of JSON. Ask for specific fields (fields: ["summary", "status", "assignee"]) rather than the default fat payload. This is the single biggest win for keeping Jira agents fast and cheap.

The remote MCP server covers Atlassian's own products. If you need agents to reach linked systems — GitHub, Slack, your own SaaS — you'll need a separate MCP server for each, or a tools layer that generates them from your existing APIs.

Data Center and Server sites don't work. No workaround. If you're on-prem, you'd need to build your own MCP server against the Jira REST API — here's the guide.