<!-- canonical: https://docs.axelabs.ai/onboard/claude-connectors -->
<!-- source: content/onboard/claude-connectors.mdx -->

---
title: AXE MCP connectors (claude.ai + Claude Code 자동 sync)
description: claude.ai 의 Custom Connector 등록에 Bitwarden 브라우저 확장 + AXE Vault `MCP Connectors` collection 활용. 4 필드 (Name / URL / Client ID / Client Secret) 를 4 곳에서 찾던 옛 방식 폐기 — 확장 한 번 열면 catalog 자동 suggest. Claude Code 로컬 앱은 같은 claude.ai 계정 로그인 시 자동 sync.
playbook: true
---

# AXE MCP connectors

axelabs 가 운영하는 MCP server (Frame · Hive · Blueprint 등) 를 본인 Claude 에 등록하는 표준 절차. 4 필드 (이름 / URL / Client ID / Client Secret) 를 4 곳에서 찾던 옛 방식 ([/onboard/claude-frame-setup](/onboard/claude-frame-setup) — legacy, MCP 마다 반복) 폐기. Bitwarden 브라우저 확장이 vault `MCP Connectors` collection 에서 URI 매칭으로 자동 suggest ([D-vault-mcp-catalog](/ops/decisions)).

> **커넥터는 claude.ai 웹 챗 통합용.** 터미널·Claude Code·Codex·Cursor·cron 처럼 셸이 있는 곳에선 커넥터를 서비스마다 등록할 필요 없이 [AXE CLI](/services/cli) 한 줄 복붙 — 로그인 1회로 전 서비스. 그 페이지의 **"에이전트에 붙여넣기"** 블록을 본인 에이전트에 그대로 붙이면 끝.

## AI 요청 프롬프트

```
https://docs.axelabs.ai/onboard/claude-connectors 따라 내 머신에 AXE MCP connector 추가해줘.

진행:
1. 내 OS + 브라우저 확인 (Chrome/Firefox/Safari/Edge)
2. Bitwarden 브라우저 확장 설치 + 본인 vault server URL 등재 + unlock 상태 진단
3. 본인 claude.ai 회사 이메일 로그인 확인
4. 페이지의 각 Step 명령 실행 + 검증, 매 step 결과 받고 다음
5. 함정 발생 시 페이지 "함정 정리" 표 따라 우회
6. Claude Code 로컬 앱 (macOS/Windows) 자동 sync 검증
```

본인 AI session = Claude Code / Cursor / ChatGPT 데스크탑 / Claude.app / 기타.

페이지 본문 = 사람이 직접 read 도 가능, AI 도 참고. AI 가 본 페이지 fetch 후 위 진행 순서대로 사용자와 step-by-step interactive 풀어나감.

## Prereq

- AXE 임직원 (`@axellc.com`) 또는 customer 직원 (`@<customer-domain>`) email
- 본인 AXE Vaultwarden 계정 (운영자 / customer IT 가 Entra SSO 가입 완료) + `MCP Connectors` collection access 권한
- 본인 claude.ai 계정 — **회사 이메일** 로그인 (개인 gmail 등 불가)
- 머신: macOS / Windows / Linux + 모던 브라우저

## Step 1: Bitwarden 브라우저 확장 install + vault server 등재

(이미 설치 + 로그인 돼 있으면 skip → Step 2)

### Chrome / Edge / Brave

[Chrome Web Store — Bitwarden Password Manager](https://chrome.google.com/webstore/detail/bitwarden-password-manage/nngceckbapebfimnlniiiahkandclblb) 에서 추가.

### Firefox

[Mozilla Add-ons — Bitwarden Password Manager](https://addons.mozilla.org/firefox/addon/bitwarden-password-manager/).

### Safari

App Store → "Bitwarden Password Manager" 설치 + Safari 환경설정 → 확장 프로그램 → Bitwarden 체크.

### Self-hosted server 등재 (필수)

확장 아이콘 클릭 → 로그인 화면 좌하단 **Settings** (gear) → **Self-hosted environment** → **Server URL** 에:

| Customer | Server URL |
|---|---|
| axe (`@axellc.com` 직원) | `https://axe.axelabs.ai/vault` |
| realchoice (`@realchoice.co.kr`) | `https://realchoice.axelabs.ai/vault` |
| (다른 customer) | 운영자 / customer IT 가 안내 |

Save → 확장 화면 복귀 → **Log in** → 회사 이메일 + 마스터 비밀번호 → unlock.

검증: 확장 popup 안에 본인 vault items 가 보이면 OK. **MCP Connectors** collection 클릭 시 N 개 (axe = 3 개: `Frame MCP (axe)` / `Hive MCP (axe)` / `Blueprint MCP (axe)`) 보이면 ready.

> realchoice 외 customer 는 customer 측 vault 의 `MCP Connectors` collection 이 아직 미구축 가능 (Q3 sovereignty 마일스톤). 비어있으면 customer IT 에게 catalog 구축 요청 — 임시 우회는 옛 [/onboard/claude-frame-setup](/onboard/claude-frame-setup) hand-find 절차.

## Step 2: claude.ai 의 Custom Connector 추가 화면 열기

[claude.ai](https://claude.ai) → 우측 상단 프로필 → **Settings** → **Connectors** → **Custom connectors** → **+ Add Custom Connector** 클릭.

폼이 열림 — 4 필드:

- **Name** (텍스트)
- **Remote MCP server URL** (URL)
- **Advanced** ▼ 펼치기 →
  - **OAuth Client ID** (텍스트)
  - **OAuth Client Secret** (password)

> 이 폼이 열린 상태로 다음 Step. 닫지 말 것.

## Step 3: Bitwarden 확장에서 catalog item 의 4 필드 가져오기

브라우저 주소창이 `https://claude.ai/customize/connectors` (또는 `https://claude.com/customize/connectors`) 인 상태에서 **Bitwarden 확장 아이콘 클릭**. URI 매칭으로 `MCP Connectors` collection 의 항목들이 popup 상단 **"Items for this site"** 섹션에 자동 suggest:

- `Frame MCP (axe)`
- `Hive MCP (axe)`
- `Blueprint MCP (axe)`

등록할 MCP 클릭 → 상세 화면. 각 필드의 **copy 버튼** ⎘ 으로 claude.ai 폼에 paste:

| Bitwarden 항목 필드 | claude.ai 폼 필드 | 메모 |
|---|---|---|
| **Name** (= item 제목, 예: `Frame MCP (axe)`) | Name | 본인 화면 라벨 — 짧게 줄여도 OK (예: `Frame`) |
| **Username** (= OAuth client_id GUID) | OAuth Client ID | Bitwarden 자동입력 가능성 있음 — 작동 안 하면 copy + paste |
| **Password** (= OAuth client_secret, 마스킹됨) | OAuth Client Secret | popup 의 👁 아이콘으로 잠시 확인 가능. 자동입력 가능성 있음 — 작동 안 하면 copy + paste |
| **Custom field "MCP URL"** | Remote MCP server URL | 표준 form field 아님 → 항상 copy + paste |

> 💡 Client ID 와 Client Secret 의 차이: Client ID 는 공개 식별자 (메일 평문 전달 OK), Client Secret 은 비밀번호 (절대 노출 X). vault 가 두 값 모두 단일 SoT 로 관리 → 본인 손에 메모/종이 보관 0.

> Bitwarden 의 자동입력 동작 여부는 claude.ai 폼의 필드 attribute (`autocomplete`, `type="password"` 등) 에 따라 다름. 자동입력 실패해도 popup 의 copy 버튼 4 클릭 으로 4 필드 채움 — 옛 방식 (4 곳 hand-find) 대비 결정적 단축.

## Step 4: Connect → Microsoft 로그인 → 첫 사용 시 동의

폼 4 필드 채운 후 **Connect** 버튼 → 브라우저가 Microsoft 로그인으로 redirect:

1. 회사 이메일 입력 (`firstname.lastname@axellc.com` 또는 customer 도메인)
2. 비밀번호 / Authenticator
3. **(첫 사용 시) 동의 화면** — `Access <MCP-name> MCP` 권한 요청 → **Accept** 클릭
4. 자동으로 claude.ai 복귀
5. Connector 상태 = **"Connected"** (녹색 점) → 성공

> 두 번째 이후 등록 (같은 customer 의 다른 MCP) 은 같은 Microsoft 계정이라 동의 화면 skip — 바로 Connected.

## Step 5: 동작 확인

claude.ai 새 채팅에서 자연어 호출:

| MCP | 자연어 예시 | Claude 가 호출하는 tool |
|---|---|---|
| Frame | `axec 의 5월 미결 항목 5 개 보여줘` | `Frame:list_open_items` |
| Frame | `axec 4월 시산표` | `Frame:query_trial_balance` |
| Hive | `이번 주 휴가 신청 보여줘` | `Hive:leave_get_request` |
| Hive | `내 급여 명세 5월` | `Hive:payroll_get_my_payslip` |
| Blueprint | `오늘 일정 추가: 14:00 회의실 A` | `Blueprint:create_event` |
| Blueprint | `Teams 메시지 본문 fetch <link>` | `Blueprint:get_teams_message` |

Claude 가 tool 호출 + 결과 자연어 정리 → 성공.

같은 절차로 나머지 MCP 도 Step 2~4 반복. catalog 가 3 개 다 보유 — **3 개 모두 등록 권장** (한 번 등록 후 영구 사용).

## Step 6: Claude Code 로컬 앱 자동 sync

같은 claude.ai 계정으로 **Claude Code 네이티브 앱** (macOS / Windows) 에 로그인하면 위에서 등록한 connector 들이 **자동 동기화** — 별도 설정 X.

검증:

1. Claude Code 앱 열기
2. `/status` → "Anthropic Account" 줄에 본인 회사 이메일 표시
3. `/mcp` → 위에서 등록한 connector 들이 목록에 보임 (`Frame` / `Hive` / `Blueprint` 등, claude.ai connector 표식 함께)
4. 채팅에서 자연어로 호출 가능

> Cursor / Cline / Witsy 같은 다른 MCP host 는 각자 별도 설정 — 본 페이지 범위 밖. 표준 `mcpServers` JSON 패턴은 동일하므로 catalog 의 4 필드 값 그대로 활용 가능 (각 host 의 config 형식만 차이).

## 함정 정리

| # | 증상 | 원인 | 우회 |
|---|---|---|---|
| 1 | Bitwarden 확장 popup 에 `MCP Connectors` collection 보이지 않음 | vault sync 안 됨 / unlock 만료 / 다른 customer vault server 에 로그인 | 확장 → Settings → **Sync vault** 클릭 / 확장 lock → unlock 재실행 / Step 1 의 server URL 본인 customer 와 일치 확인 |
| 2 | claude.ai 페이지에서 확장 클릭 시 매칭 항목 0 — 다른 사이트의 일반 item 만 보임 | catalog item 의 URI 가 등록되지 않음 (catalog 갱신 누락) | 운영자 (`ai@axellc.com`) 에게 보고 — `axe mcp publish` 재실행 필요. 임시 우회 = `MCP Connectors` collection 을 확장 안에서 직접 열어 item 수동 copy |
| 3 | Bitwarden 자동입력이 OAuth Client ID/Secret 칸에 작동 안 함 | claude.ai 폼의 필드 attribute 가 표준 `username`/`password` 아님 | popup 의 각 필드 옆 **copy 버튼** 사용 + 폼에 paste (4 클릭) — 정상 우회 |
| 4 | "Remote MCP server URL" 칸이 자동입력 안 됨 | URL 은 custom field (`MCP URL`) 라 표준 form field 아님 | item popup → Custom fields 섹션 → MCP URL 옆 copy 버튼 → 폼에 paste — 항상 manual (claude.ai 폼 구조상 영구) |
| 5 | Connect 클릭 후 Microsoft → `AADSTS50011: redirect_uri mismatch` | 본인 customer 외 다른 customer 의 URL 입력 (예: realchoice 직원이 axe URL) | Step 1 의 customer 별 server URL 표 + Step 3 의 item 본인 customer 의 것 확인 |
| 6 | Connect 후 Microsoft → `AADSTS500011: resource not found` | MCP app 의 `application_id_uri` 가 본인 회사 Entra tenant 에 등록 안 됨 (다른 customer 의 vault item 일 수 있음) | 본인 customer 의 vault 사용 확인 / 운영자 / customer IT 에 보고 |
| 7 | 동의 화면이 안 뜨고 바로 Connected | 이미 처음 한 번 동의함 — 재동의는 Settings → Connectors → Disconnect → re-Connect 시점에만 발생 | 정상. 권한 변경 필요 시 Disconnect 후 재연결 |
| 8 | Connected 표시 후에도 채팅에서 tool 호출 안 됨 | claude.ai 가 tool 목록 fetch 중 또는 connector 비활성 | 1~2 분 대기 후 새 채팅 / Settings → Connectors → 본 connector toggle off → on |
| 9 | Bitwarden 확장에 master password 입력 후에도 `MCP Connectors` 안 보임 | 본인이 해당 collection 의 멤버 아님 (organization 권한 미부여) | 운영자 (`ai@axellc.com`) 에게 본인 email 으로 collection access 요청. axe 측 = ai / soohun / taehun / jinwoo 4명 기본 access |
| 10 | Claude Code 네이티브 앱에 `/mcp` 가 비어있음 (Step 6) | claude.ai 와 다른 Anthropic 계정으로 로그인됨 / sync 지연 | `/login` → claude.ai 와 같은 회사 이메일 / Claude Code 앱 재시작 → 1~2 분 대기 |

## 매 작업 시 사전 작업

| 빈도 | 작업 | 자동화 |
|---|---|---|
| 1회 (초기 setup) | Step 1~4 (extension + vault + claude.ai 등록) | — |
| Vault timeout 마다 | Bitwarden 확장 unlock (master password) | ✅ Bitwarden 의 vault timeout 설정 (확장 → Settings → Vault timeout) |
| Secret rotation 발생 시 | (없음 — 운영자가 `axe secret rotate` 실행 시 catalog 자동 재발행, Bitwarden sync 후 확장에서 새 secret 자동) | ✅ [D-vault-mcp-catalog](/ops/decisions) step 4.5 hook |
| 매 claude.ai 사용 | (없음) | — |

## 참조

- [D-vault-mcp-catalog](/ops/decisions) — 본 catalog 모델 (Vaultwarden org collection + `axe mcp publish` CLI + `axe secret rotate` 자동 hook)
- [/architecture/secrets#mcp-connectors-catalog-d-vault-mcp-catalog-2026-05-26](/architecture/secrets) — catalog 구조 도식 + 신규 MCP 추가 3-step 표준 절차
- [/onboard/claude-frame-setup](/onboard/claude-frame-setup) — Frame 단독 connector 옛 절차 (4 필드 hand-find, legacy — 본 페이지로 대체 권장)
- [/onboard/vault-setup](/onboard/vault-setup) — Vault setup 표준 (KDF + 4 client 셋업)
- [/onboard/m365-connector](/onboard/m365-connector) — Microsoft 365 connector (별 MCP 가 아님, 보조 reading)
- [B-customer-sovereignty-architecture](/ops/backlog) — customer 측 vault catalog 분리 (Q3 milestone)
- [/ops/known-gaps](/ops/known-gaps) "매니페스트 / vault 측 미해결" — bw cache stale 함정 (운영자 측, end-user 무관)