Source Integrations

Bitbucket

Connect a Bitbucket Cloud repository to an MCP server using either an OAuth consumer or an App Password. Bitbucket has two quirks worth front-loading: the composite username:app_password token shape and the two-hour OAuth access-token lifetime.

When to pick Bitbucket

Pick Bitbucket if your team already standardises on Atlassian. Repositories are addressed as workspace/repo_slug (for example myworkspace/app), and the credential model is App Password by default with OAuth available for one-shot human onboarding.

Option A — Connect with Bitbucket (OAuth)

Click Connect with Bitbucket on the integration form, complete the consent screen on Bitbucket, and you will land back on the integration's edit page. OAuth is great for developer onboarding and one-shot imports — see Access Token Lifetime below for why long-lived production integrations should currently prefer App Passwords.

Access token lifetime

Bitbucket OAuth access tokens live for two hours. Refresh-token handling is not yet wired in the integration. As a result, OAuth-sourced integrations stop authenticating two hours after connection. For long-lived production use, prefer App Passwords until refresh-token handling lands.

Option B — App Password

App Passwords are the long-lived option until refresh-token handling lands. Mint one at https://bitbucket.org/account/settings/app-passwords/ with the minimum scopes:

Account: Read — required by the validation call to GET /user.
Repositories: Read — required to list repositories, branches, trees, and fetch files.

Do NOT grant Repositories: Write or Repositories: Admin: The Vectoralix import pipeline is strictly read-only. The provider does not inspect the credential's actual scope set, so the stored token's blast radius is whatever you granted at issue time. If a write- or admin-scoped App Password is ever pasted in, revoke it on the Bitbucket side and issue a fresh read-only credential.

The composite token format

Bitbucket is the only provider whose Personal Access credential is two fields joined by a colon: username:app_password. The backend detects the colon and switches to HTTP Basic auth. If there is no colon, the value is treated as an OAuth bearer token.

Paste your App Password into the Access Token field in this exact format:

username:app_password

Repository addressing

Repository Name takes the workspace/repo_slug form, for example myworkspace/app. Both segments come straight from the Bitbucket URL.

API endpoints used

Method	Endpoint	Purpose
GET	`/user`	Authenticate token, capture identity
GET	`/repositories?role=member`	List accessible repositories (paginated)
GET	`/repositories/{workspace}/{repo}/refs/branches`	List branches (paginated)
GET	`/repositories/{workspace}/{repo}/src/{commit}/{path}`	List directory entries — walked breadth-first

Tree traversal cost vs GitHub

Bitbucket has no recursive-tree endpoint, so the integration walks one request per directory. To keep the worst case bounded, four caps apply:

Cap	Value	Meaning
Maximum depth	5	Subtrees deeper than 5 levels relative to the branch root are truncated.
Maximum files	10,000	Hard ceiling on files collected per call.
Maximum HTTP requests	200	Caps wide directory fan-outs.
Wall clock budget	30s	Hard timeout enforced via a monotonic deadline.

Scenario	GitHub	Bitbucket
1 directory, 50 files	1	1
20 directories, 500 files	1	20
200 directories, 10,000 files	1	Up to 200 (capped)

Rate limits

Bitbucket allows roughly 1,000 requests per hour per user-workspace pair. The integration honours Retry-After when the provider sends it and otherwise backs off for 60 seconds.

Troubleshooting

Symptom	What it means
401 or 403 on auth	Bad credential or missing Account: Read. Verify your App Password format is exactly username:app_password.
429	Per-hour rate limit. Wait the suggested Retry-After interval and retry.
Tree truncated warning	Repository exceeded one of the four traversal caps. Use a path filter to scope the import to the directory you actually need.