사용자 가이드

bbmcp 는 AI 도구가 Bitbucket 을 다룰 때 내가 볼 수 있는 것만 보도록 막아 주는 게이트웨이입니다. 이 문서는 사용자가 직접 하는 일(키 발급, 클라이언트 연결, 승인)을 다룹니다. 서비스 설정은 관리자 가이드를 보십시오.

1. 로그인

브라우저로 사내 bbmcp 주소를 열면 로그인 화면이 나옵니다. Keycloak SSO 가 켜져 있으면 이미 SSO 세션이 있는 경우 자동으로 로그인됩니다(사일런트 SSO). 자동으로 들어가지지 않으면 Keycloak 계정으로 로그인 을 누르십시오.

2. 개요 화면

로그인하면 개요 화면이 열립니다. 활성 키 수, 사용 가능한 도구 수, 대기 중 승인, 현재 REST 인증 모드를 한눈에 볼 수 있고, MCP 연결에 필요한 엔드포인트도 여기서 복사할 수 있습니다.

Bitbucket 사용자 매핑이 없습니다 경고가 보이면 아직 내 Keycloak 계정이 Bitbucket 사용자와 연결되지 않은 상태입니다. 이 상태에서는 권한이 필요한 도구를 쓸 수 없으니 관리자에게 식별 매핑 등록을 요청하십시오.

3. API 키 발급과 회전

MCP 클라이언트는 개인 API 키로 bbmcp 에 접속합니다. 키는 내 권한을 넘지 못하며, 언제든 회전하거나 폐기할 수 있습니다.

3.1 발급

1. 좌측 메뉴에서 API 키 를 엽니다.
2. 우측 상단 키 발급 을 누릅니다.
3. 용도를 알 수 있는 이름을 적습니다(예: Claude Code, CI 리뷰 봇).
4. 권한 역할을 고릅니다. 필요하면 스코프를 더 좁힐 수 있습니다.
5. 발급하면 키 값이 한 번만 표시됩니다. 복사해 안전한 곳에 보관하십시오.

3.2 회전

키가 노출됐거나 회전 주기가 되면 회전 을 누르십시오. 새 키가 즉시 발급되고, 기존 키는 관리자가 정한 유예 시간 동안 함께 동작한 뒤 만료됩니다. 그 사이에 클라이언트 설정을 바꾸면 중단 없이 교체할 수 있습니다. 유출이 확실하면 유예를 기다리지 말고 폐기 를 누르십시오 — 즉시 무효화됩니다.

3.3 역할과 스코프

4. MCP 클라이언트 연결

개요 화면의 엔드포인트와 발급한 키를 클라이언트 설정에 넣습니다.

{
  "mcpServers": {
    "bbmcp": {
      "type": "http",
      "url": "https://bbmcp.company.local/mcp",
      "headers": {
        "Authorization": "Bearer bbmcp_xxxxxxxx_yyyyyyyy"
      }
    }
  }
}

연결되면 클라이언트의 도구 목록에 bitbucket_* 도구가 나타납니다. 보이는 도구는 내 역할과 키 스코프로 거른 결과입니다.

5. 사용 가능한 도구

사용 가능한 도구 화면에서 내가 호출할 수 있는 도구와 입력 스키마를 확인할 수 있습니다. 리뷰 작업이라면 bitbucket_pr_review_context 하나로 PR 정보·diff·커밋·댓글·활동을 한 번에 가져오는 것이 가장 빠릅니다.

6. 승인 요청

PR 댓글 작성처럼 쓰기 등급 작업을 호출하면 bbmcp 가 먼저 APPROVAL_REQUIRED 로 거절하고 승인 요청을 만듭니다. 승인 요청 화면에서 내용을 확인하고 승인한 뒤, 같은 인자로 다시 호출하면 실행됩니다.

• 쓰기 등급(PR 생성·댓글·수정, 브랜치 생성)은 본인이 직접 승인할 수 있습니다.
• 실행 등급(머지·승인·거절)은 서비스 관리자가 승인해야 합니다.
• 승인 후 인자를 바꾸면 APPROVAL_STALE 로 거부됩니다. 다시 요청하십시오.
• 머지 승인은 PR version 에 묶입니다. 새 커밋이 올라오면 승인이 무효가 됩니다.

7. Bitbucket 개인 토큰 (선택)

기본값인 서비스 계정 모드에서는 PR 댓글의 작성자가 서비스 계정으로 남고, 본문 머리에 [MCP 요청자: 내아이디] 가 붙습니다. Bitbucket 상의 작성자까지 본인으로 만들어야 한다면 Bitbucket 토큰 화면에서 개인 액세스 토큰을 등록하십시오.

1. Bitbucket → 프로필 → Personal access tokens 에서 토큰을 발급합니다.
2. bbmcp 의 Bitbucket 토큰 화면에 붙여 넣고 저장합니다.
3. 연결 확인 으로 토큰이 유효한지 점검합니다.
4. 인증 모드에서 "내 요청에 개인 토큰을 우선 사용" 을 켭니다.

8. 내 권한 확인

어떤 저장소에 접근이 막혔다면 내 권한 조회 에서 원인을 확인하십시오. Bitbucket 유효 권한과 MCP 접근 정책 판정을 함께 보여 줍니다.

9. AI 리뷰 보조

관리자가 AI 를 활성화했다면 AI 리뷰 보조 에서 모델과 대화할 수 있습니다. 응답은 기본적으로 스트리밍으로 표시되고, 최대 출력 토큰은 관리자가 정한 상한(최대 256k) 안에서 조절할 수 있습니다. Ctrl+Enter 로 전송합니다.

10. 내 활동 기록

내 계정으로 수행된 도구 호출과 인증 기록을 확인할 수 있습니다. 실패한 호출은 사유가 함께 표시되어 권한 문제인지 정책 문제인지 바로 구분됩니다.

11. 개인 설정

테마(시스템/밝게/어둡게), 글자 크기(90~140%), 표시 언어를 설정할 수 있습니다. 글자 크기는 브라우저가 아니라 계정에 저장되므로 다른 기기에서 접속해도 유지됩니다. 로컬 계정이라면 이 화면에서 비밀번호도 변경합니다.

12. 오류 메시지