BB-DC-MCP — Bitbucket Data Center MCP Server

A Model Context Protocol server for Bitbucket Data Center, built with the official mcp SDK v2 (MCPServer, Python 3.12).

Every REST call runs as the calling user: the server is broker-only — each caller links their Bitbucket account once (OAuth 2.0 authorization code + PKCE against Bitbucket's native OAuth 2.0 Provider API), and their tokens live encrypted in the server's Postgres token store. There is no bot fallback, no PAT passthrough, and no unsigned-header identity mode.

Architecture

User ──► MCP client (LibreChat / Claude Code / …), Okta PKCE
              │
              ▼
       agentgateway         ← validates the Okta JWT, applies tool RBAC
              │  POST /mcp    (streamable HTTP, stateless)
              │  Authorization: Bearer <okta access token>
              │  X-MCP-Gateway-Secret: <shared secret>
              ▼
       BB-DC-MCP            ← re-verifies the token (defense in depth),
              │               maps sub → the caller's own Bitbucket token
              ▼
       Bitbucket DC         ← native per-user permissions and audit

• Transport: MCP streamable HTTP, stateless, endpoint /mcp — one process serves both the 2026-07-28 protocol revision and legacy (initialize) clients.

• Identity: derived exclusively from the verified Okta access token (MCP_OKTA_ISSUER / MCP_OKTA_AUDIENCE); the immutable sub claim keys the token broker.

• First link: when the broker holds no token for the caller, the tool returns a URL elicitation (2026-07-28 clients) or a consent-link error text (legacy clients); the user approves once in the browser and retries.

• Scope tiers: two incoming Application Links — read tools use the PROJECT_READ REPO_READ grant, write tools the separate REPO_WRITE grant — so read-only usage never holds a write-capable token.

Design details and operational notes: docs/broker-mode.md.

Related MCP server: Bitbucket Cloud MCP Server

Deploying

Step-by-step (namespace, secrets, the two Application Links, gateway wiring, verification, troubleshooting): docs/deploy-bitbucket.md.

• k8s/ — kustomize base: the server Deployment (broker env included), token-store Postgres, NetworkPolicy, token GC CronJob.

• k8s/argocd/application.yaml — ArgoCD Application deploying the base (or your per-cluster overlay of it).

Local development:

uv sync --all-extras          # install
uv run pytest -q              # tests (all Bitbucket/Okta HTTP is faked)
uv run ruff check .           # lint
uv run mypy servers/          # strict type check

MCP_DEV_USER=jane.doe uv run bitbucket-server     # local stdio run
MCP_TRANSPORT=http uv run bitbucket-server        # streamable HTTP at :8000/mcp

Container image: ghcr.io/betasystems/bb-dc-mcp/bitbucket (linux/amd64 + linux/arm64), built by CI from Dockerfile.

Releasing

Releases are semver git tags; deployments pin the matching image tag instead of :latest.

Every merge to main releases automatically, sized by semantic-release (.releaserc.json) from the commit messages since the last tag:

CI dry-runs semantic-release to compute the version, builds + scans the multi-arch image, publishes :X.Y.Z, :X.Y, and :latest, then semantic-release creates the tag and the GitHub Release with conventional-commit notes.

Manual tag pushes (git tag v1.0.0 && git push origin v1.0.0) remain as an escape hatch — the pipeline releases them unchanged and semantic-release continues from the new baseline. Bump version in pyproject.toml only for such manual milestones (automated releases don't rewrite it; the image's OCI version label always carries the released version).

Trust boundary

A captured Okta token is replayable for its validity window, so deployments must combine:

1. Okta re-verification (MCP_OKTA_ISSUER/MCP_OKTA_AUDIENCE, required; optional MCP_OKTA_AUTHORIZED_PARTY pins azp) — independent of the gateway's own JWT validation.

2. MCP_GATEWAY_SECRET — constant-time-checked shared secret the gateway sends as X-MCP-Gateway-Secret; blocks direct token replay at the pods.

3. NetworkPolicy (k8s/networkpolicy.yaml) — ingress restricted to the gateway data plane.

4. MCP_STRICT_AUTH=1 (production) — fail closed unless the gateway secret, Okta verification, and shared request-state keys are configured. An Okta JWKS outage returns 503 (not a misleading 401).

Product tokens never travel through the gateway: they are minted at consent by Bitbucket's OAuth 2.0 provider and stored encrypted at rest (AES-256-GCM envelope; KMS-wrapped data key in production).

📁 Bitbucket Data Center

MCP Apps views

On clients that negotiate the io.modelcontextprotocol/ui extension, list_pull_requests renders an interactive PR health table and get_pull_request a PR lifecycle view (open → review → merge-ready) — pure renderers of the tool result, served as ui://bitbucket/* resources (servers/bitbucket/ui.py). Other clients get the same markdown text; no extra tools or RBAC surface exist.

For hosts that speak MCP-UI instead of MCP Apps (e.g. Goose), set BITBUCKET_UI_INLINE_FALLBACK=true: clients that did not negotiate the extension then additionally get a self-contained rendering of the view (data baked in, no handshake) embedded as a text/html resource in the tool result. Off by default — plain-text clients would only see a large HTML block. Every PR-view call logs the negotiation outcome, so the pod log shows which path a client took.

PR health (list_pull_requests) — state/age/review chips with two composable client-side filter rows (state × review hygiene: unassigned, awaiting approval, needs work, ready to merge, draft, stale >30d), each chip carrying its count; clicking a row opens the PR in Bitbucket:

PR lifecycle (get_pull_request) — the PR's gate pipeline plus reviewers and description:

(Screenshots are the real ui://bitbucket/* views rendered against sample data, in the host's light theme.)

Tools (20)

Env prefix: BITBUCKET_ (product settings) and MCP_ (shared server settings). The full configuration surface is documented in k8s/configmap.yaml and k8s/secret.yaml.example.

Write tools mutate Bitbucket state as the caller (separate REPO_WRITE grant, native audit attribution).

License

MIT