> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mcpmanager.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect Bitbucket

> Connect Bitbucket Cloud through the Atlassian Rovo MCP server. Unlike Jira and Confluence, Bitbucket tools authenticate only with a scoped API token — not OAuth — so this guide covers the two admin prerequisites (an org-linked workspace and API-token authentication enabled in the Rovo MCP server settings), creating a scoped token, and connecting it in MCP Manager with an Authorization header.

Bitbucket Cloud rides on the **same Atlassian Rovo MCP server** as Jira and Confluence — but it connects differently. Bitbucket Cloud tools authenticate **only with a scoped API token**, never OAuth. So even with a perfectly working Atlassian Rovo **OAuth** connection, you will see **no Bitbucket tools at all** — they require a separate, token-authenticated connection plus two pieces of admin setup.

<Note>
  The [Atlassian Rovo guide](/mcp-server-guides/atlassian) covers the **OAuth** path: paste the URL, approve a consent screen, and you get Jira,
  Confluence, and Compass. That path's [authentication detection](/mcp-server-guides/overview#how-mcp-manager-detects-the-authentication-type) lands
  on **Standard OAuth** — and OAuth does **not** expose Bitbucket. To reach Bitbucket you connect the same server with an API token instead, which
  uses MCP Manager's **Token in custom headers** method. This guide covers that path.
</Note>

<Info>
  This guide is a convenience based on Atlassian's setup at the time of writing. **Atlassian's own [Rovo MCP Server
  documentation](https://support.atlassian.com/atlassian-rovo-mcp-server/docs/configuring-authentication-via-api-token/) is authoritative** and may be
  more current. The requirements below — the org-linked workspace, admin-enabled API-token auth, the scopes, and the header format — come from
  Atlassian, not from MCP Manager. If a step here has drifted or a connection problem is specific to how Atlassian works, **Atlassian support** is the
  fastest path to an answer.
</Info>

## Why you don't see Bitbucket tools over OAuth

This is the question most people arrive with: *"I already connected Atlassian Rovo and it works for Jira — why are there no Bitbucket tools?"*

Because Atlassian gates Bitbucket behind a different authentication method. The Rovo MCP server accepts **two** ways to authenticate, and they expose different tool sets:

| How you connect                             | What it exposes                                                                 | Bitbucket? |
| :------------------------------------------ | :------------------------------------------------------------------------------ | :--------- |
| **OAuth 2.1** (the one-click consent flow)  | Jira, Confluence, Compass, and shared platform tools (e.g. `searchAtlassian`)   | **No**     |
| **Scoped API token** (Authorization header) | Jira, Confluence, Bitbucket, Jira Service Management, and shared platform tools | **Yes**    |

The split that trips people up: **Compass is OAuth-only**, while **Bitbucket and Jira Service Management are API-token-only**. Jira, Confluence, and the shared platform tools work either way. OAuth support for Bitbucket is on Atlassian's roadmap but **not available yet** — until then, the API-token path below is the only way to get Bitbucket tools. A useful consequence: because a scoped token can *also* carry Jira and Confluence scopes, one token connection can expose Bitbucket alongside most of Atlassian (Compass excepted) — see [Gotchas](#gotchas--things-to-keep-in-mind).

```mermaid theme={null}
%%{init: {'theme':'base','themeVariables':{'fontFamily':'Lato, sans-serif','lineColor':'#6a6b76','primaryColor':'#e0e2e8','primaryTextColor':'#12141d','primaryBorderColor':'#6a6b76','edgeLabelBackground':'#ffffff','textColor':'#12141d'}}}%%
flowchart TD
  S["🔌<br/>Atlassian Rovo MCP server<br/>mcp.atlassian.com/v1/mcp"] --> O["OAuth 2.1<br/>browser consent, no keys"]
  S --> T["Scoped API token<br/>Authorization: Basic or Bearer"]
  O --> SHARED["Jira, Confluence,<br/>shared platform tools<br/>(searchAtlassian, Teamwork Graph)"]
  T --> SHARED
  O --> COMPASS["Compass"]
  T --> JSM["Jira Service Management"]
  T --> BB["Bitbucket Cloud"]
  classDef auth fill:#aed8ff,color:#062b4c,stroke:#0b4880,stroke-width:1.5px;
  classDef shared fill:#e0e2e8,color:#12141d,stroke:#6a6b76,stroke-width:1.5px;
  classDef oauthonly fill:#d9c6ff,color:#062b4c,stroke:#6b46c1,stroke-width:1.5px;
  classDef tokenonly fill:#2fedb4,color:#062b4c,stroke:#059669,stroke-width:1.5px;
  class O,T auth;
  class SHARED shared;
  class COMPASS oauthonly;
  class JSM,BB tokenonly;
```

**How to read it:** grey = reachable with **either** method; green = **API token only** (Bitbucket Cloud and Jira Service Management); purple = **OAuth only** (Compass). This is the picture **today** — Atlassian has said OAuth for Bitbucket is coming, which would add an `O → BB` path.

## Before you start

Most of the work is on the Atlassian side, and two parts of it require an **administrator**. Line these up before you open MCP Manager:

* **An org-linked Bitbucket workspace.** *(Admin)* Bitbucket Cloud MCP tools only work for a workspace that's **linked to an Atlassian organization**. Atlassian's linking deadline of **15 March 2026** has passed, so most eligible paid workspaces have already been linked (auto-linked from 16 March 2026 onward) — but confirm yours is linked, and to the **right** organization, since linking can't be undone. See [Linking your workspace](#connect-the-server) below.
* **API-token authentication enabled for the Rovo MCP server.** *(Admin)* This is **off by default** — only OAuth works until an Atlassian **organization admin** turns it on under **Atlassian Administration → Rovo → Rovo MCP server → Authentication**. Without it, the Bitbucket tools cannot authenticate at all.
* **A scoped API token** with the Bitbucket scopes for the tools you need (see [Scopes and tools](#scopes-and-tools)). This is either a **personal API token** (used with Basic auth — acts as you) or a **service-account API key** (used with Bearer auth — a shared identity). Both must be **scoped** tokens.
* **The ability to add a server in MCP Manager** — the **Basic server management** capability. If you don't see the option to add a server, ask a workspace administrator. See the [capabilities reference](/deployment/rbac-and-roles/capabilities).

<Tip>
  For a credential the whole team will share, use a **service-account API key** (Bearer) tied to a dedicated Atlassian account rather than your
  personal token. The connection then survives someone leaving, and every Bitbucket action is attributable to a clearly named non-human identity. For
  per-person accountability instead, have each user bring their **own** personal token — see [Identity and attribution](#identity-and-attribution).
</Tip>

## Scopes and tools

Atlassian groups the Bitbucket tools into two scope sets — **`read_bitbucket`** and **`write_bitbucket`**. Grant your token only the scopes for the tools you actually need; over-provisioned tokens are the leading cause of unintended access.

**Read tools (`read_bitbucket`):**

| Tool                   | Actions                              | Required scope               |
| :--------------------- | :----------------------------------- | :--------------------------- |
| `bitbucketWorkspace`   | list, get                            | `read:workspace:bitbucket`   |
| `bitbucketRepository`  | list, get, defaultReviewers          | `read:repository:bitbucket`  |
| `bitbucketRepoContent` | branch.get, commit.get, files.get    | `read:repository:bitbucket`  |
| `bitbucketPullRequest` | list, get, comments, diff            | `read:pullrequest:bitbucket` |
| `bitbucketUser`        | pullRequests                         | `read:pullrequest:bitbucket` |
| `bitbucketPipeline`    | list, get, steps, step.get, step.log | `read:pipeline:bitbucket`    |
| `bitbucketDeployment`  | list, get                            | `read:pipeline:bitbucket`    |
| `bitbucketEnvironment` | list, get                            | `read:pipeline:bitbucket`    |

**Write tools (`write_bitbucket`):**

| Tool                   | Actions                         | Required scope                |
| :--------------------- | :------------------------------ | :---------------------------- |
| `bitbucketPullRequest` | create, merge, approve, comment | `write:pullrequest:bitbucket` |
| `bitbucketRepoContent` | branch.create, commit.create    | `write:repository:bitbucket`  |
| `bitbucketPipeline`    | run                             | `write:pipeline:bitbucket`    |
| `bitbucketEnvironment` | create, delete, update          | `admin:pipeline:bitbucket`    |

Start read-only — `read:repository:bitbucket`, `read:pullrequest:bitbucket`, and `read:pipeline:bitbucket` cover most "explore the codebase, review PRs, check why a build failed" workflows. Add write scopes only when you need the agent to create PRs, push commits, or trigger pipelines.

## Connect the server

<Steps>
  <Step title="Link the Bitbucket workspace to an Atlassian organization (admin)">
    A user who is **both** a Bitbucket workspace admin **and** an Atlassian organization admin links the workspace at [admin.atlassian.com](https://admin.atlassian.com/): select the organization, go to **Apps** (or **Atlassian apps**), open the **…** (More) menu, and choose **Link Bitbucket**.

    <Warning>
      Linking is **permanent** — a workspace can't be unlinked or moved to another organization afterward. Pick the organization that already hosts your Jira and Confluence so identity, billing, and Jira–Bitbucket links stay together.
    </Warning>

    Most paid workspaces are already linked (the 15 March 2026 deadline has passed). If yours isn't, and it doesn't appear in the **Select a workspace to link** list, it isn't yet eligible — Atlassian notifies you when it becomes eligible.
  </Step>

  <Step title="Enable API-token authentication for the Rovo MCP server (admin)">
    An Atlassian **organization admin** turns on API-token authentication: **Atlassian Administration → Rovo → Rovo MCP server**, then in the **Authentication** section turn **API token** on. This is off by default, and the Bitbucket tools cannot authenticate until it's enabled.

    <Info>
      API-token connections aren't governed by the Rovo MCP server's domain allowlist (that applies to OAuth). They're governed by your organization's **IP allowlist** and the **scopes** on the token. If you use IP allowlisting, MCP Manager's egress must be permitted — see [Gotchas](#gotchas--things-to-keep-in-mind).
    </Info>
  </Step>

  <Step title="Create a scoped API token">
    Go to [id.atlassian.com → Security → API tokens](https://id.atlassian.com/manage-profile/security/api-tokens) and create a token **with scopes**. When prompted, select the Bitbucket scopes your tools need from [Scopes and tools](#scopes-and-tools) above — for example `read:repository:bitbucket`, `read:pullrequest:bitbucket`, and `read:pipeline:bitbucket` for read-only access.

    * For a **personal API token**, create it on your own Atlassian account. You'll pair it with your email in the next step.
    * For a **shared service-account API key**, create it on a dedicated service account; it's used on its own as a Bearer token.

    <Warning>
      Copy the token now — Atlassian shows it only once. Scopes are fixed at creation: if a tool later returns a permission error, the token is missing that scope and you'll need to create a new one with it.
    </Warning>
  </Step>

  <Step title="Add the server in MCP Manager with the Authorization header">
    On the [Servers](https://app.mcpmanager.ai/settings/servers) page, add a server and paste the Atlassian Rovo MCP URL:

    ```text Atlassian Rovo MCP URL theme={null}
    https://mcp.atlassian.com/v1/mcp
    ```

    **Don't click Continue yet.** Expand **Add connection headers (optional)** on that same screen and add one header. Supplying it here tells MCP Manager to skip OAuth discovery and connect with your token instead — which is what surfaces the Bitbucket tools.

    | Field                              | Value                             |
    | :--------------------------------- | :-------------------------------- |
    | Header name                        | `Authorization`                   |
    | Header value (personal token)      | `Basic <base64(email:api_token)>` |
    | Header value (service-account key) | `Bearer <api_key>`                |

    For a **personal token**, the value is the word `Basic`, a space, then the base64 of `email:api_token`. Generate it with:

    ```bash macOS / Linux theme={null}
    echo -n "you@example.com:YOUR_API_TOKEN" | base64
    ```

    ```powershell Windows (PowerShell) theme={null}
    [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes("you@example.com:YOUR_API_TOKEN"))
    ```

    For a **service-account key**, the value is simply `Bearer ` followed by the key — no email, no base64.

    Click **Continue**. MCP Manager stores the header value encrypted with **AES-256-GCM**, attaches it to every request it makes to Atlassian, and the Bitbucket tools (plus any Jira/Confluence scopes your token carries) become available to add to a gateway.
  </Step>
</Steps>

## Identity and attribution

The header credential you just added is **not** shared with everyone by default. MCP Manager stores it against a **single identity**, and that identity's **Availability** defaults to **Private** — *"Only available to your user account."* Other users on the same gateway use their **own** identity, and the token value of a private identity is visible only to its creator. Two patterns follow:

* **Per-user tokens (the default).** Each person brings their **own** personal API token (`Basic <base64(email:api_token)>`) as a Private identity. Every Bitbucket action is then attributable to that individual, both in MCP Manager's logs and — because Basic auth carries their email — in Bitbucket's own audit trail. Configure the server assignment as per-user identity in the gateway and each teammate is prompted for their own token. See [Identity Controls](/features/identity-controls).
* **One shared service-account credential.** Use a service-account API key (`Bearer <api_key>`) and set the identity's **Availability** to **Global** — *"Available to all users in your organization"* — on the server's **Identities** tab (only the creator can change it). Everyone on the gateway then acts as that one service account. Bitbucket's logs attribute every call to the service account; MCP Manager's logs still attribute to the real user who made the request.

<Tip>
  You can have both. Add the server twice — once with a Global, read-only service-account key for frictionless shared reads, and once as a per-user,
  write-capable connection where each person supplies their own token so writes carry their identity in Bitbucket. See [Adding the same server more
  than once](/mcp-gateway-concepts/mcp-gateways#adding-the-same-server-more-than-once).
</Tip>

See [per-user versus shared identity](/security/authentication-and-identity#per-user-identity-versus-shared-identity) for how this maps to gateway identity schemes.

## Gotchas & things to keep in mind

* **OAuth never surfaces Bitbucket tools.** This is the single most common point of confusion. If you connected Atlassian Rovo by approving a consent screen, you have an OAuth connection — Jira, Confluence, and Compass only. Bitbucket requires the API-token connection described here. The two are separate connections and can coexist.
* **The two admin prerequisites are non-negotiable.** Without an **org-linked workspace** *and* **API-token authentication enabled** in the Rovo MCP server settings, the Bitbucket tools cannot authenticate — no token, however well scoped, will work.
* **Your header credential is Private by default, not global.** Adding headers creates one identity scoped to you; it does **not** expose the token to everyone. Sharing org-wide is an explicit choice — set the identity's **Availability** to **Global** on the server's Identities tab. See [Identity and attribution](#identity-and-attribution).
* **One token can serve most of Atlassian.** A scoped API token can include Jira, Confluence, and Jira Service Management scopes alongside Bitbucket's, so a single token connection can expose all of those at once — **Compass is the exception** (it's OAuth-only). If you already have a working **OAuth** connection for Jira/Confluence/Compass, the cleanest split is to keep it and add this token connection **just for Bitbucket**.
* **Use `/v1/mcp`, not `/v1/sse`.** The legacy `https://mcp.atlassian.com/v1/sse` endpoint is being retired — Atlassian stops supporting it after **30 June 2026**. Newer OAuth clients may use `https://mcp.atlassian.com/v1/mcp/authv2`, but for the token-header path use `https://mcp.atlassian.com/v1/mcp`.
* **Scopes are fixed at token creation.** You can't edit a token's scopes afterward. If a tool returns a permission error, the token lacks that scope — create a new token with it and update the header value in MCP Manager.
* **IP allowlists still apply.** API-token connections bypass the domain allowlist but are still subject to your organization's Atlassian **IP allowlist**. If you enforce one, allow MCP Manager's egress IPs — find the current list at [MCP Manager's IP ranges](https://app.mcpmanager.ai/enterprise/ip-ranges) (machine-readable [JSON](https://app.mcpmanager.ai/enterprise/ip-ranges.json)) — or calls will be blocked. This is an Atlassian-side network control.

## Further reading

<CardGroup cols={2}>
  <Card title="Connect Atlassian Rovo" icon="atlassian" href="/mcp-server-guides/atlassian">
    The OAuth path for Jira, Confluence, and Compass — the companion to this guide.
  </Card>

  <Card title="Find & Connect MCP Servers" icon="compass" href="/mcp-server-guides/overview">
    How MCP Manager detects authentication type, and how to find other servers' URLs.
  </Card>

  <Card title="Per-user versus shared identity" icon="users" href="/security/authentication-and-identity#per-user-identity-versus-shared-identity">
    What a shared token means for attribution, and how per-user identity works.
  </Card>

  <Card title="Connect your AI client" icon="plug" href="/tutorials/connect-your-ai-client">
    Point Claude, Cursor, or another client at the gateway once Bitbucket is connected.
  </Card>
</CardGroup>

## External sources

<CardGroup cols={2}>
  <Card title="Bitbucket Cloud tools on the Rovo MCP server" icon="bitbucket" href="https://support.atlassian.com/atlassian-rovo-mcp-server/docs/supported-tools/">
    Atlassian's authoritative list of Bitbucket tools and the scopes each requires.
  </Card>

  <Card title="Configuring authentication via API token" icon="key" href="https://support.atlassian.com/atlassian-rovo-mcp-server/docs/configuring-authentication-via-api-token/">
    Atlassian's own reference for the Basic and Bearer header formats and the API-token flow.
  </Card>

  <Card title="Linking your workspace to an organization" icon="link" href="https://support.atlassian.com/bitbucket-cloud/kb/linking-your-bitbucket-cloud-workspace-to-an-atlassian-organization/">
    The admin steps to link a Bitbucket workspace — a prerequisite for Bitbucket MCP tools.
  </Card>

  <Card title="Bitbucket Cloud now on the Rovo MCP server" icon="bitbucket" href="https://www.atlassian.com/blog/bitbucket/the-atlassian-rovo-mcp-server-now-supports-bitbucket-cloud">
    Atlassian's announcement — workflows, the tool set, and current limitations.
  </Card>
</CardGroup>