---
name: iblai-connect-jira
description: "Read and write Jira data through the Jira Cloud platform REST API v3 and expose it to an ibl.ai agent as an MCP tool. Use when the user asks an agent to work with Jira data, or to set up a Jira MCP connection on ibl.ai."
metadata:
  kind: guide
---

# Jira connector for AI agents

> A starting point maintained on ibl.ai at https://ibl.ai/developer/connectors/jira — not part of the iblai/vibe repository. Checked against Atlassian's documentation on October 20, 2026; test it against your own Jira setup before you rely on it.

Jira Cloud holds projects, issues (work items) with their fields, comments, attachments, workflows and transitions, sprints and boards, and the users and permissions around them.

## Auth & conventions

- **API:** Jira Cloud platform REST API v3 (REST). Issues, projects, comments, workflows and transitions, users and fields. JQL search runs at /rest/api/3/search/jql (GET or POST) with nextPageToken paging; the old /rest/api/3/search was removed.
- **Base URL:** https://{your-domain}.atlassian.net/rest/api/3/
- **Access:** Public, self-serve. Any Jira Cloud user can create an API token at id.atlassian.com. Apps register in the Atlassian developer console for OAuth 2.0 (3LO). Calls run with the user's own project permissions.
- **Auth:** Basic auth with email and API token; OAuth 2.0 authorization code (3LO). Basic auth base64-encodes email:api_token. OAuth 3LO authorizes at auth.atlassian.com; calls go to https://api.atlassian.com/ex/jira/{cloudid}/; offline_access returns rotating refresh tokens.
- **Limits:** Points-based hourly quota (65,000 points/hour global pool by default), burst limits (100 RPS GET/POST, 50 RPS PUT/DELETE per endpoint) and per-issue write limits. 429 with Retry-After and RateLimit-Reason headers.
- Keep Jira credentials in environment variables or the ibl.ai credential store. Never print a token in chat and never commit one to a file.
- Destructive or outward-facing calls are marked **Confirm with the user first** — do.

## Reads

- **JQL search** — GET or POST /rest/api/3/search/jql; page with nextPageToken. Use POST for long JQL.
- **Issues** — Get an issue with its fields, status and assignee from the Issues group of the v3 API.
- **Transitions** — GET /rest/api/3/issue/{issueIdOrKey}/transitions lists transitions the user can perform.
- **Comments** — Read the comments on an issue.

## Writes

- **Create issue** — Create an issue in a project with summary, issue type and fields.
- **Transition issue** — POST /rest/api/3/issue/{issueIdOrKey}/transitions; needs Browse projects and Transition issues permissions.
- **Edit issue or add comment** — Update fields or add a comment to an issue.
- **Delete issue** — Delete an issue; needs the delete permission in the project. **Confirm with the user first.**

## Expose it to an ibl.ai agent (MCP)

Atlassian publishes an official MCP server, Atlassian Rovo MCP Server (https://support.atlassian.com/atlassian-rovo-mcp-server/docs/getting-started-with-the-atlassian-remote-mcp-server/). Register it below as-is, or host your own server that wraps the calls in this skill.

First install the ibl.ai platform skills and connect your organization (writes `IBLAI_ORG`, `IBLAI_USERNAME` and `IBLAI_API_KEY` to `.env`):

```bash
npx skills add iblai/vibe --all
# then, in your coding agent:
/iblai-api-login
```

Every call below sends `Authorization: Api-Token $IBLAI_API_KEY`.

1. **Register the server** — `POST https://api.iblai.app/dm/api/ai-mentor/orgs/$IBLAI_ORG/users/$IBLAI_USERNAME/mcp-servers/` with `name`, `url`, `transport` (`sse` | `websocket` | `streamable_http`) and `auth_type` (`none` | `token` | `oauth2`). Capture the returned `id`.
   - Jira supports per-user OAuth: `auth_type=oauth2` with `auth_scope=user` and a linked `oauth_service` makes each person connect their own account in the chat. It needs an `auth_{provider}` credential in the organization's credential store first.
2. **Create the connection** — `POST https://api.iblai.app/dm/api/ai-mentor/orgs/$IBLAI_ORG/users/$IBLAI_USERNAME/mcp-server-connections/` with `server`, `scope` (`platform` | `mentor` | `user`), `auth_type`, and either `credentials` + `authorization_scheme` or a `connected_service` id for OAuth. Credentials are masked on read; never send a masked value back.
3. **Enable it on the agent** — `GET https://api.iblai.app/dm/api/ai-mentor/orgs/$IBLAI_ORG/users/$IBLAI_USERNAME/mentors/{agent_id}/settings/`, add `mcp-tool` to `tool_slugs` and the server id to `mcp_servers`, then `PATCH` the full lists back. They are replaced, not merged.

Full reference: https://ibl.ai/developer/platform/mcp/mcp-connections and the `/iblai-api-agent-mcp` skill.

## Example prompts

- "List all open bugs in the PAY project assigned to me, sorted by priority"
- "Create a story in MOBILE for the login timeout fix and link it to PAY-142"
- "Move PAY-210 to In Review and add a comment with the PR link"
- "Summarize what the platform team completed in the last sprint"

## Guardrails

- Issues and comments hold internal business, engineering and customer data; service desk tickets may include personal data depending on the organization.
- Request the narrowest Jira scopes or role the task needs, and prefer a read-only credential for agents that only answer questions.
- Return the fields the user asked for, not whole records; do not paste personal data into chat that the user did not request.
- Before any write, show the user exactly what will change and wait for a yes.
- Respect the documented limits above: page through results and back off on rate-limit responses instead of retrying in a loop.

## References

- OAuth 2.0 (3LO) apps: https://developer.atlassian.com/cloud/jira/platform/oauth-2-3lo-apps/
- Jira Cloud rate limiting: https://developer.atlassian.com/cloud/jira/platform/rate-limiting/
- Getting started with the Atlassian MCP server: https://support.atlassian.com/atlassian-rovo-mcp-server/docs/getting-started-with-the-atlassian-remote-mcp-server/
- Atlassian Rovo MCP Server: https://support.atlassian.com/atlassian-rovo-mcp-server/docs/getting-started-with-the-atlassian-remote-mcp-server/
- This connector on ibl.ai: https://ibl.ai/developer/connectors/jira
- ibl.ai MCP server connections: https://ibl.ai/developer/platform/mcp/mcp-connections