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.