The Atlassian Rovo guide covers the OAuth path: paste the URL, approve a consent screen, and you get Jira,
Confluence, and Compass. That path’s authentication detection 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.
This guide is a convenience based on Atlassian’s setup at the time of writing. Atlassian’s own Rovo MCP Server
documentation 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.
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 |
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 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). 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.
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_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 |
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
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: select the organization, go to Apps (or Atlassian apps), open the … (More) menu, and choose Link Bitbucket.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.
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.
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.
Create a scoped API token
Go to id.atlassian.com → Security → API tokens and create a token with scopes. When prompted, select the Bitbucket scopes your tools need from 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.
Add the server in MCP Manager with the Authorization header
On the Servers page, add a server and paste the Atlassian Rovo MCP URL: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.
For a personal token, the value is the word For a service-account key, the value is simply
Atlassian Rovo MCP URL
| Field | Value |
|---|---|
| Header name | Authorization |
| Header value (personal token) | Basic <base64(email:api_token)> |
| Header value (service-account key) | Bearer <api_key> |
Basic, a space, then the base64 of email:api_token. Generate it with:macOS / Linux
Windows (PowerShell)
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.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. - 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.
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.
- 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 legacyhttps://mcp.atlassian.com/v1/sseendpoint is being retired — Atlassian stops supporting it after 30 June 2026. Newer OAuth clients may usehttps://mcp.atlassian.com/v1/mcp/authv2, but for the token-header path usehttps://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 (machine-readable JSON) — or calls will be blocked. This is an Atlassian-side network control.
Further reading
Connect Atlassian Rovo
The OAuth path for Jira, Confluence, and Compass — the companion to this guide.
Find & Connect MCP Servers
How MCP Manager detects authentication type, and how to find other servers’ URLs.
Per-user versus shared identity
What a shared token means for attribution, and how per-user identity works.
Connect your AI client
Point Claude, Cursor, or another client at the gateway once Bitbucket is connected.
External sources
Bitbucket Cloud tools on the Rovo MCP server
Atlassian’s authoritative list of Bitbucket tools and the scopes each requires.
Configuring authentication via API token
Atlassian’s own reference for the Basic and Bearer header formats and the API-token flow.
Linking your workspace to an organization
The admin steps to link a Bitbucket workspace — a prerequisite for Bitbucket MCP tools.
Bitbucket Cloud now on the Rovo MCP server
Atlassian’s announcement — workflows, the tool set, and current limitations.