Agentic Data Plane
Preview

Jira Managed MCP Server

The Jira managed MCP server lets agents search, read, and manage Jira issues. It authenticates with either a shared API token (Basic authentication) or, for per-user identity, user-delegated OAuth. With OAuth it’s the enterprise counterpart to the Slack setup guide, and Atlassian’s flow has its own scope model and quirks worth calling out.

After reading this page, you will be able to:

  • Configure the Jira managed MCP server with Basic authentication or Atlassian’s OAuth flow

  • Pick the right scopes for the tools your agents use

  • Walk a user through the consent flow and verify the connection

What this MCP server does

The Jira managed type exposes the following read tools:

  • query: Search for issues using a JQL query. Returns the matching issues as JSON.

  • get_issue: Retrieve a single issue by its key, for example PROJ-123.

  • list_projects: Return visible Jira projects, optionally filtered by a search query.

  • get_transitions: Return the available workflow transitions for an issue.

It also exposes the following write tools:

  • create_issue: Create a new issue.

  • update_issue: Update fields on an existing issue.

  • transition_issue: Move an issue to a new workflow state.

  • add_comment: Add a comment to an issue.

  • add_worklog: Log time spent on an issue.

  • create_issue_link: Create a directional link between two issues.

It can also expose Jira issues and projects as SQL-queryable tables, through two more tools that are off by default. See Expose Jira data as SQL tables.

Prerequisites

  • A Jira (Atlassian Cloud) site and its base URL, for example https://mycompany.atlassian.net.

  • Credentials for one of the following authentication modes:

    • Basic Auth: An Atlassian account email and an API token from id.atlassian.com, with the token stored in the Redpanda Agentic Data Plane secret store.

    • User OAuth: Your own Atlassian OAuth 2.0 (3LO) app, created in the Atlassian developer console, plus an OAuth Provider in Redpanda Agentic Data Plane that uses the Atlassian / Jira preset and carries the app’s client credentials. See Configure User-Delegated OAuth.

Atlassian’s scope model (user-delegated OAuth)

When you use user-delegated OAuth, Atlassian uses a granular, prefixed scope namespace. Request these scopes as a set:

Scope Allows

read:jira-work

Read Jira project and issue data and search for issues. Needed for the read tools.

write:jira-work

Create and edit issues, post comments, and create worklogs. Needed for the write tools.

offline_access

Issue a refresh token so Redpanda can refresh expired access tokens without asking the user to consent again.
Every scope in the server’s Required scopes must also be in the OAuth provider’s scope list, and in the scopes you added to the Atlassian app in the developer console. The Atlassian / Jira preset requests read:jira-work, write:jira-work, read:confluence-content.all, and offline_access. A required scope the provider doesn’t request makes tool calls fail with scope_upgrade_required until each user reconnects and grants it. If the Atlassian app isn’t allowed to grant that scope, every tool call keeps failing.

Configure

  1. Open MCP servers in the sidebar.

  2. Click Add MCP server.

  3. Click the Jira card in the marketplace picker.

  4. Replace the suggested Name, and optionally add a Description.

  5. In the Jira configuration form:

    • Base URL: Your Jira instance URL, for example https://mycompany.atlassian.net.

    • Max Results Per Page (optional): Page size for the query tool when a call doesn’t set one. Leave it at 0 to use the default, 50.

    • Auth: Select Basic Auth or User OAuth.

      • For Basic Auth: Provide the account email and the API-token secret reference.

      • For User OAuth: Pick the Atlassian OAuth Provider you configured, and set Required scopes to read:jira-work and offline_access. Add write:jira-work if your agents use the write tools.

    • Enabled under Queryable (optional): Off by default. Leave it off unless your agents need the two SQL tools. See Expose Jira data as SQL tables.

  6. Click Create server.

The create form turns Enable code mode on by default for this server type. rpk ai mcp-server create leaves it off unless you pass --code-mode. See Code Mode.

Expose Jira data as SQL tables

The Jira server can present its data as two read-only SQL tables instead of only as tools, so an agent can filter Jira records the way it would query a database. SQL exposure is the Enabled toggle under Queryable in the server’s configuration, and it’s off by default, so an existing server gains nothing until someone turns it on. Turning it on adds two tools:

  • list_tables: Return the table catalog. For each table, the catalog lists its columns and their types, which columns can be filtered and with which operators, whether each filter is exact, the page-size limit, and a schema fingerprint that every query response repeats so a caller can tell when the catalog changed.

  • execute_query: Run one query against a table and return a page of rows plus a cursor for the next page.

Both tools read Jira through the server’s configured authentication, so with user-delegated OAuth a query returns only the records the calling user can see, exactly as the other tools do. Neither tool writes to Jira.

The tables are:

Table Contents

issues

Jira issues, from Jira’s issue search. Columns: key, project, issue_type, status, priority, summary, description, assignee, reporter, created, updated, and labels. The description column carries the issue description flattened to Markdown. The assignee and reporter columns hold Atlassian account IDs.

projects

Jira projects, from Jira’s project search. Columns: id, key, name, and type.

Not every column can be filtered. A filter is offered only where Jira’s search never drops a matching row, but most filters can return extra rows:

  • On issues, filter on key, project, issue_type, status, or priority for a value or a list of up to 100 values, on assignee or reporter by account ID (and on assignee, whether the issue is unassigned), and on created or updated with a time range. Matching on key, project, issue_type, status, and priority is case-insensitive, so a status filter for done also returns issues in Done. A time range is widened by 15 hours on each side before it reaches Jira, so it can return issues created or updated outside the range. Only the assignee and reporter filters are exact. The summary, description, and labels columns can be returned but not filtered.

  • On projects, filter on id or key for a value or a list of up to 50 values, or on type for a single value. Matching on key and type is case-insensitive, and only the id filter is exact. The name column can be returned but not filtered. A query on this table takes one filter per column, and it can’t filter on id and key together, so pick whichever identifier you have.

Because execute_query returns the rows Jira sends back without re-checking them against your filters, an agent that needs exact results must re-apply its filters to the rows it receives. The list_tables catalog marks which filters are exact.

A list longer than the cap fails rather than being silently cut short.

Two more limits are worth designing around:

  • Every query against issues needs a filter. At least one predicate on key, project, issue_type, status, priority, assignee, reporter, created, or updated is required, and an unfiltered query is refused before Jira is called. A query against projects has no such requirement.

  • A paged scan is best-effort. A page holds at most 100 rows for issues and 50 for projects, and Jira keeps changing under a multi-page scan, so a long scan can miss a row or return one twice. A cursor is bound to the query that produced it. Reusing one with different filters or against another table is refused instead of quietly starting a new scan.

With SQL exposure on, the two tools are available to every caller of the server, including agents. Leave it off on a server whose agents should only reach the curated Jira tools.

  1. Open the Inspector tab.

  2. Run the query tool with a small JQL filter.

  3. The first call fails with a connection-required result that carries an Atlassian authorization URL.

  4. Open the authorization URL. Atlassian asks you to pick a site (Cloud instance) and approve the scopes.

  5. Atlassian redirects back. Your connection appears under Connections.

  6. Run the search again. Results come back.

Use with agents

Point an agent at the Server URL on the server’s Connection tab. Each user calling the agent will trigger their own consent flow on first call.

With user-delegated OAuth, set the server’s required_scopes to every scope your agents' tools need before users connect. An Atlassian app can request only scopes you’ve already added to it in the developer console, and if you widen required_scopes later, users who already connected have to consent again.

Troubleshooting

Symptom What to check

token_expired errors soon after users connect

offline_access wasn’t in the scopes at consent time, so Redpanda has no refresh token. Add it to the provider and to required_scopes, then have users reconnect.

"Resource not found" for a project the user has access to

Atlassian’s OAuth grants are site-scoped. The user authorized for one Cloud instance; the project lives on another. They need to re-consent with the second site.

scope_upgrade_required after widening scopes

The server’s required scopes were extended after users consented, so users reconnect to grant them. If it persists after reconnecting, a required scope is missing from the provider’s scopes or from the Atlassian app.

invalid_grant during refresh

Refresh tokens expire if unused for ~90 days. The user re-consents.

Limitations

  • Atlassian app management: The OAuth app and its callback URLs are managed in developer.atlassian.com, not in Agentic Data Plane.

  • Jira Server / Data Center (self-hosted): This MCP type targets Atlassian Cloud. Self-hosted Jira may need a self-managed MCP server instead. See Register a self-managed MCP server.

  • Confluence access: Separate scope namespace; not exposed by this MCP server.

  • SQL exposure is read-only: The execute_query tool reads issues and projects. Use the write tools to change anything in Jira. See Expose Jira data as SQL tables.

Next steps