Jira Cloud

Jira Cloud integration provides 53 MCP tools across issue management, agile/sprint workflows, and Jira Service Management (JSM).

Prerequisites

• Jira Cloud instance (not Jira Server/Data Center)
• Atlassian account with admin access to create OAuth apps
• Access to developer.atlassian.com

OAuth App Setup

1. Create an OAuth 2.0 (3LO) app

   Go to developer.atlassian.com/console/myapps and click Create > OAuth 2.0 integration.

2. Configure permissions

   In your app settings, go to Permissions and add these scopes:

   Scope	Access
   read:jira-work	Read issues, projects, boards, filters
   write:jira-work	Create/manage issues, comments, worklogs
   read:jira-user	View and search users
   manage:jira-project	Manage project settings, components, versions
   read:board-scope:jira-software	Read boards
   write:board-scope:jira-software	Manage boards
   read:sprint:jira-software	Read sprints
   write:sprint:jira-software	Manage sprints
   offline_access	Required for refresh tokens
   read:me	User profile information

3. Set the callback URL

   Under Authorization, add the callback URL:

   https://api.switchboard.fpdigital.ai/oauth/jira/callback

4. Copy credentials

   Note the Client ID and Client Secret from the app settings.

5. Set environment variables

   cd src
   npx wrangler secret put JIRA_CLIENT_ID
   npx wrangler secret put JIRA_CLIENT_SECRET

How OAuth Works for Jira

Jira uses Atlassian OAuth 2.0 (3LO) which has several differences from standard OAuth:

Audience Parameter

The authorization URL requires audience=api.atlassian.com — this is unique to Atlassian and not used by other Switchboard services.

JSON Token Exchange

Token exchange uses a JSON request body instead of form-encoded data (unlike most OAuth providers). Switchboard handles this automatically.

Cloud ID Discovery

After obtaining an access token, Switchboard automatically calls the accessible-resources endpoint to discover your Jira Cloud ID. This ID is required for all API calls and is stored alongside your tokens.

Note

If you have access to multiple Atlassian sites, the first accessible site is used. Multi-site selection will be added in a future update.

Rotating Refresh Tokens

Jira refresh tokens are rotating — each time a token is refreshed, the old refresh token is invalidated and a new one is issued. Switchboard handles this automatically, always storing the latest refresh token.

Token	Lifetime
Access token	1 hour
Refresh token	90 days (rotating)

Available Tools

53 tools across 12 categories:

Category	Tools	Examples
Connection	1	jira_ping
Issue Management	10	search, get, create, update, transition, assign
Comments	2	add, get comments
Worklogs	2	log work, get worklogs
Projects	4	list, get, components, versions
Boards & Sprints	8	list boards/sprints, sprint issues, create sprints
Sprint Lifecycle	3	start, complete, move to backlog
Epics & Labels	4	list epics, add/remove labels, link issues
Utilities	7	watchers, filters, fields, statuses, priorities
Delete Operations	4	delete issues, comments, worklogs, attachments
Service Management	4	service desks, queues, SLAs, create requests
Advanced	4	changelog, permissions, link types, request types

Common Gotchas

JQL Search

Jira uses JQL (Jira Query Language), not free-text search. Examples:

• project = "PROJ" AND status = "In Progress"
• assignee = currentUser() AND sprint in openSprints()
• created >= -7d ORDER BY priority DESC

Issue Keys vs IDs

Always use issue keys (e.g., PROJ-123) not numeric IDs. Keys are human-readable and stable; numeric IDs are internal only.

Status Transitions

You cannot set a status directly. Use jira_transition_issue with the status name (e.g., “In Progress”) — Switchboard auto-resolves the transition ID.

Rich Text (ADF)

Jira uses Atlassian Document Format (ADF), not Markdown. Switchboard automatically converts Markdown to ADF for create/update/comment operations, and converts ADF back to readable text for display.

DLP Patterns

Switchboard automatically detects and blocks Jira-specific credentials:

Pattern	Severity
Atlassian API tokens (ATATT-prefix)	Critical (auto-block)
OAuth bearer token references	High
Webhook shared secrets	High

Testing

After setup, verify the connection:

1. Go to your Switchboard Dashboard
2. Navigate to the Jira service page
3. Click Connect to initiate OAuth
4. After authorization, click Test Connection
5. The test calls jira_ping and displays your authenticated user info