Atlassian

Connecting Atlassian to NeuBird lets you investigate Jira issues from NeuBird and from Jira itself. On the Marketplace path, a Jira admin authorizes NeuBird through Atlassian’s Rovo MCP OAuth consent screen. Refresh and access tokens stay in Jira (Forge encrypted storage). NeuBird never stores an Atlassian user API token.

The Jira administrator who installs, pairs, and authorizes the app does not need a NeuBird account.

Quick start

1. Install NeuBird from the Marketplace.
2. In NeuBird, create an Atlassian connection (Forge app auth) and generate a pairing code.
3. In Jira, open Apps → NeuBird, enter the code, then click Authorize NeuBird.
4. Attach that connection to a NeuBird project.
5. On a work item, open Agents → Browse agents → NeuBird → Enable, then assign or @mention NeuBird.

If consent is blocked, an org admin must allowlist the Forge redirect URL, then authorize again.

---

Configuration

Setup is split on purpose. Pairing fields on the NeuBird connection are output-only (site URL, cloud ID, pairing code). Marketplace authorization happens on the Jira admin page — not by pasting a token into NeuBird.

In NeuBird (Connections)

Create the connection with Forge app auth. Do not type forge into a text field, and do not paste an API token here.

Field	Required	Where it is	Description
Name	Yes	Create / edit form	A descriptive name for this connection
Description	No	Create / edit form	Optional notes
Auth mode	Yes	Create / edit form	Forge app for Marketplace installs. API token is the legacy path only
Generate code	After save	Configuration tab → Connect a Jira site	Mints a one-time pairing code. Not a form field
Linked site URL	After pairing	Configuration tab → Connect a Jira site	Written back when Jira redeems the code. Read-only

After pairing and OAuth, NeuBird investigations vend a short-lived Bearer access token at query time from the app. Editing the connection name or description does not clear the linked site.

In Jira (Apps → NeuBird)

Field	Required	Description
Pairing code	Yes, once	Paste the code from NeuBird. Format NB-XXXX-XXXX. Single-use, expires in 15 minutes
Authorize NeuBird	Yes, after pairing	Opens Atlassian’s Rovo MCP OAuth consent screen. No API token is collected

The admin page shows Atlassian access: Authorized with OAuth after consent succeeds. Disconnecting unbinds the site and clears the stored OAuth tokens; it does not delete the NeuBird connection.

Attach the connection to a project

Investigations started from Jira need a NeuBird project that includes this Atlassian connection. Add it under Projects the same way you attach any other data source. If the connection is not on a project, assigning NeuBird on a Jira issue cannot start a session.

---

Create a Forge-auth connection

In NeuBird, go to Connections, add an Atlassian connection, and choose Forge app as the auth mode. You do not paste an API token here.

After you save, generate a pairing code on this same connection (see Pair the NeuBird app in Jira below). Pairing is not a form field — it lives under Connect a Jira site on the Configuration tab.

You can also generate a pairing code on an existing API token connection. Pairing binds the Jira site; it does not convert that connection to Forge or drop a stored token.

---

Pair the NeuBird app in Jira

Do this after the data-source connection exists. Pairing binds your Jira site to this NeuBird organization. Without it, the NeuBird app in Jira cannot resolve your deployment.

1. In NeuBird, go to Connections and open your Atlassian (Jira) connection.

2. Open the Configuration tab.

3. Under Connect a Jira site, click Generate code.

   

4. Copy the pairing code. NeuBird shows it in plaintext once. It is single-use and expires in 15 minutes.

   

5. Send the code to whoever administers your Jira site.

6. In Jira, they open Apps → NeuBird and enter the code once.

   

When pairing succeeds, the NeuBird connection shows the linked Jira site URL under Connect a Jira site. Then authorize NeuBird on that same Jira admin page.

If the code expires or you need another site

On the same Configuration tab, click Generate code again (or New code if a live code is still on screen). A new code does not invalidate the previous one — the old code expires on its own schedule. Generate another if it lapses or if you need to link a different Jira site.

---

Authorize NeuBird (OAuth)

After pairing, a Jira admin must grant NeuBird access through Atlassian’s official consent screen. NeuBird never asks for a user API token on this path.

1. In Jira, open Apps → NeuBird.
2. Confirm the site is connected (organization name is shown).
3. Click Authorize NeuBird. A new tab opens Atlassian’s Rovo MCP consent screen.
4. Review the access request and approve it.
5. Close the consent tab and return to Apps → NeuBird. The page should show Atlassian access: Authorized with OAuth.

If consent succeeds immediately, you are done. Attach the connection to a NeuBird project and use NeuBird in Jira.

If you see a redirect-URL allowlist error

Some Atlassian organizations block OAuth until an organization admin (not only a Jira site admin) allowlists the Forge callback URL. The error looks like:

Your organization admin must authorize access from this redirect URL to this site. Contact your organization admin to authorize access from https://<app-id>.hello.atlassian-dev.net/x1/… to site yourcompany.atlassian.net.

The host hello.atlassian-dev.net is the Forge development environment. The production Marketplace app uses a different host. The /x1/… path is a Forge webtrigger identifier — it looks random and changes if the app is uninstalled and reinstalled. Always allowlist the exact URL from the error.

Do this, then authorize a second time:

1. Copy the full https://… redirect URL from the error.
2. Have an organization admin add that URL on the Rovo MCP domain allowlist (next section).
3. Return to Apps → NeuBird and click Authorize NeuBird again (use a private window if the first attempt is still cached).

Adding the domain does not finish the connection by itself. You must complete consent after the allowlist is in place.

---

Allowlist the Rovo MCP callback domain

These steps require an Atlassian organization admin. Official references: Fix OAuth consent block and Rovo MCP server settings.

1. Sign in at admin.atlassian.com and select your organization.
2. Go to Rovo → Rovo MCP server.
3. Open Domain settings (or Domains).
4. Click Add domain.
5. Paste the full redirect URL from the error (including https:// and the /x1/… path). If the field only accepts a pattern, add https://<the-host>/**.
6. Save.

If the URL already appears in the list but consent still fails, delete the entry, add the same URL again, save, then retry Authorize NeuBird in a private window. Atlassian’s enforcement service sometimes does not pick up the first save.

This allowlist is organization-wide and one-time per callback URL. A new install (or moving from the development app to the production Marketplace app) produces a new URL and needs its own entry.

---

Use NeuBird in Jira

The issue panel is read-only: it lists NeuBird signals already linked to that issue. You start and continue investigations from Jira’s Agents / Rovo agent card, not from a Start session button on the panel.

Enable the NeuBird agent (once per site)

After the app is installed, NeuBird can show as Unavailable until someone enables it for work items:

1. Open any Jira work item.
2. Open Agents → Browse agents.
3. Select NeuBird → Start session → Enable.

There is no Studio Surfaces page for this agent. Enabling it here is what makes assign, mention, and chat available.

Start or continue an investigation

On a work item, use the NeuBird agent card:

• Assign the issue to NeuBird, or
• @mention NeuBird in the Agents / chat UI, or
• Continue in Chat (or Resume work) on an existing NeuBird agent session

Jira then starts (or continues) a NeuBird investigation for that issue. Status comes back on the agent card as the task updates. NeuBird does not post progress as issue comments.

A comment that only @mentions NeuBird through the REST API or a plain issue comment does not start an investigation. Use the Agents / assign / chat controls.

What you should see

Surface	What it shows
Jira agent card	Running / completed / failed status for the investigation started from this issue
Jira issue panel	Linked NeuBird signals for the issue key, with a link into NeuBird
NeuBird Investigations	The full session, RCA, and chain of thought

If assign fails with a project error, add the Atlassian connection to a NeuBird project and try again. If the issue panel says NeuBird is not connected, a Jira admin still needs to redeem a pairing code under Apps → NeuBird. If investigations cannot read Jira, complete Authorize NeuBird (and the domain allowlist if that error appeared).

---

Legacy: API token stored in NeuBird

Use this only when the Forge app is not installed (for example a non-Marketplace or customer-hosted setup). Choose API token as the auth mode and enter:

Field	Required	Description
Name	Yes	A descriptive name for this connection
Description	No	An overview of what this connection is used for
API Token	Yes	The Rovo MCP scoped API token
Instance URL	Yes	Your Atlassian instance URL (e.g., https://yourcompany.atlassian.net)

This path is not part of the Marketplace app surface. Marketplace installs should use Forge app auth and Authorize NeuBird — do not create or paste a user API token.

To mint a legacy Rovo MCP token, an organization admin must enable API token under Rovo → Rovo MCP server → Authentication, then create a scoped token at id.atlassian.com for the Rovo MCP app (not Rovo MCP V2).

---

For general instructions on creating and managing connections, see the Connections Overview.