Skip to content

Jira Integration

Prerequisites

This guide assumes you've completed the Quick Start and have a working summon config check.

summon-claude connects to Jira via the Atlassian Rovo MCP server, giving Claude read-only access to Jira issues, projects, Confluence pages, and related metadata directly from Slack sessions.

Setup

Authenticate with Jira using OAuth 2.1 (PKCE + Dynamic Client Registration):

summon auth jira login

This opens a browser for Atlassian OAuth consent. No Atlassian admin privileges are required — the flow uses your personal Atlassian account. Once complete, the token is stored securely in summon's config directory with 0600 permissions.

Cloud site selection

If your Atlassian account has access to multiple cloud sites, you'll be prompted to choose one:

Multiple Atlassian cloud sites found:
  1. My Company (https://mycompany.atlassian.net)
  2. Side Project (https://sideproject.atlassian.net)
Select a site [1]:

To skip the interactive prompt, pass --site:

# Short form (appends .atlassian.net automatically)
summon auth jira login --site mycompany

# Full hostname
summon auth jira login --site mycompany.atlassian.net

Cloud site UUID

The --site flag resolves to an Atlassian cloud UUID via API discovery. If discovery fails (e.g., network issues), the hostname is stored as a fallback. Re-run summon auth jira login if Jira tools report site-related errors.

Verifying authentication

summon config check

Or check Jira specifically:

summon auth jira status

Removing credentials

summon auth jira logout

This removes the stored OAuth token, client credentials, and cloud site metadata.

How it works

When Jira credentials are configured, summon adds the Atlassian Rovo MCP server to every Claude session's mcp_servers list. This uses Atlassian's HTTP transport (no local binary required). The MCP connection is lazy — it only connects when Claude first uses a Jira tool, so startup time is unaffected.

Token refresh

Access tokens are short-lived (typically 1 hour). summon handles refresh automatically via two mechanisms:

  • Daemon proxy (primary): When the daemon is running, a localhost reverse proxy transparently refreshes tokens per-request. Sessions never see expired tokens.
  • Session startup (fallback): When no proxy is available, each session refreshes the token before building the MCP config. Concurrent sessions use file-based locking (fcntl.flock) to prevent races.

If refresh fails, the session proceeds without Jira tools (logged as a warning, not fatal). You should not need to re-authenticate unless you revoke access in your Atlassian account settings.

Available tools

Claude gets access to the Atlassian Rovo MCP tool set, including:

  • Jira issues: search via JQL, get issue details, list projects, look up users
  • Confluence pages: read page content, list spaces, search via CQL
  • Metadata: issue types, link types, transitions, labels, remote links

The specific tools available depend on the Rovo MCP server version. All 31 currently known tools are classified into permission tiers.

Permission model

summon enforces a strict read-only permission model for Jira. All tools are classified at startup — no runtime discovery surprises.

Auto-approved (read-only): Tools matching get*, search*, or lookup* prefixes, plus atlassianUserInfo. These run without user confirmation.

Hard-denied (write operations): createJiraIssue, editJiraIssue, transitionJiraIssue, addCommentToJiraIssue, addWorklogToJiraIssue, and all Confluence write tools. Claude cannot perform write operations even if prompted.

Hard-denied (security): fetchAtlassian — a generic ARI accessor that bypasses tool-level gating and could access resources outside the intended scope.

Fail-closed: Any unknown Jira tool (e.g., from a future Rovo MCP update) is denied by default until explicitly classified.

No HITL tier for Jira

Unlike GitHub, Jira has no "requires Slack approval" tier. The OAuth scope is read:jira-work — write operations would fail at the API level even if summon allowed them. The hard-deny list provides defense-in-depth.

For the full tool-by-tool breakdown, see the Permissions reference.

PM agent integration

When PM agents are configured with Jira, they automatically triage Jira issues during each periodic scan cycle.

Per-project JQL filters

Associate a JQL filter with a project to control which issues the PM agent triages:

# Set a JQL filter when registering a project
summon project add myproject ./myproject --jql "project = MYPROJ AND status != Done"

# Update the filter for an existing project
summon project update myproject --jql "project = MYPROJ AND assignee = currentUser()"

# Clear the filter (PM scans all visible issues)
summon project update myproject --jql ""

Without a --jql filter, the PM agent scans all issues visible to the authenticated user.

Common JQL patterns

Use case JQL
Single project project = MYPROJ AND status != Done
Assigned to me assignee = currentUser() AND status != Done
High priority project = MYPROJ AND priority in (Critical, Blocker)
Recently updated project = MYPROJ AND updated >= -7d
Sprint backlog project = MYPROJ AND sprint in openSprints()
Unassigned bugs project = MYPROJ AND type = Bug AND assignee is EMPTY

How PM triage works

On each scan cycle, the PM agent:

  1. Calls searchJiraIssuesUsingJql with the project's JQL filter and cloud ID.
  2. Assesses urgency based on priority, due date, and labels.
  3. For high/critical issues: posts a summary to the PM's Slack channel and optionally notifies relevant child sessions via session_message.
  4. Updates the canvas under a "Jira Issues" section to track triaged issues.
  5. For normal-priority issues: updates the canvas only (no Slack notification).

Canvas state tracking prevents re-alerting on previously triaged issues. The PM reads its canvas on startup to restore the triaged-issue set.

Prompt injection defense

Jira issue content (summaries, descriptions, comments) may contain adversarial text. The PM agent is instructed to treat all issue text as untrusted data — it summarizes and triages, but never follows instructions found in issue content.

Scribe integration

Scribe sessions are wired to the Jira MCP server with Jira-aware system prompts (untrusted-content warnings, Gmail/Jira dedup) and scan prompts (mentions, assignments, status changes via JQL).

When both Google Workspace and Jira are active, the scribe system prompt instructs Gmail deduplication — Jira notification emails (from jira@ or noreply@ at atlassian.net domains) are skipped since they're covered by direct Jira monitoring.

Troubleshooting

See the Jira troubleshooting section for common issues and solutions.

See also