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

---
title: 문제 해결
description: Frame connector 설정 시 자주 발생하는 오류와 대응.
---

# 문제 해결

## "Couldn't reach the MCP server"

claude.ai 가 frame 서버에 도달 못 함. 원인 후보:

1. **URL 오타** — `https://axe.axelabs.ai/frame/mcp` (마지막에 `/mcp` 포함)
2. **회사 customer 와 다른 URL** — `axe` 직원은 `axe.axelabs.ai`, `realchoice` 직원은 `realchoice.axelabs.ai`
3. **claude.ai 캐시** — connector 완전 삭제 후 시크릿 창에서 재등록 시도

curl 로 외부 reachability 확인:
```bash
curl -sS https://axe.axelabs.ai/frame/health
# → {"status":"ok","service":"frame-mcp"}
```

200 OK 안 나오면 운영자에게 알리세요.

## "Authorization with the MCP server failed"

Microsoft 인증 또는 그 다음 단계에서 실패. URL 바의 `error_code=` 와 `entra_aadsts_code=` 가 결정적 단서.

### Reconnect 후에도 401 — frame middleware 의 RFC 9728 metadata path

**증상**: Connector 가 "Connection has expired. You can reconnect to re-authenticate" 표시 → Reconnect 클릭 → Microsoft 로그인 성공 (Entra Trace ID 있음, AADSTS error code 없음) → 다시 같은 메시지 반복.

**원인**: frame middleware 의 `/frame/mcp/.well-known/oauth-protected-resource` (resource-level RFC 9728 metadata) path 가 unauthenticated allowlist 누락 시 401 반환. claude.ai Connector 가 OAuth challenge metadata 못 받아 reconnect flow 진행 불가.

**해소**: **D-ops-23 (2026-05-22)** — `src/frame/mcp/http_server.py` 의 `_PUBLIC_PATHS` + `inner.router` 양쪽에 resource-level path 추가. 본 시점 이후 reconnect 정상.

**검증 명령**:
```bash
curl -sS -o /dev/null -w "%{http_code}\n" \
    https://<customer>.axelabs.ai/frame/mcp/.well-known/oauth-protected-resource
# 200 expected (D-ops-23 이전엔 401)
```

### `/frame/schemas` 또는 `/hive/schemas` 401 — auth-required (정상)

**증상**: `curl https://axe.axelabs.ai/frame/schemas` 가 401 반환. WWW-Authenticate: Bearer header 동반.

**원인**: 의도된 동작. `/schemas` 는 RFC 9728 metadata 와 달리 **`_PUBLIC_PATHS` 미포함** — Blueprint artifact 지식 레이어 ([D-bp-artifact-1](/ops/decisions)) 의 schema discovery 가 MCP 토큰 인증 필요. 토큰 없이 호출 시 일반 MCP 호출과 동일 401.

**해소**: MCP 토큰 (`FRAME_MCP_TOKEN` 또는 OAuth bearer) 부여 후 재시도. Blueprint 가 자동 호출 시는 [`B-bp-artifact-schema-discovery`](/ops/backlog) 가 frame token 재사용.

```bash
curl -H "Authorization: Bearer $FRAME_MCP_TOKEN" \
    https://axe.axelabs.ai/frame/schemas
# 200 + { version, service, schemas } envelope expected
```

### AADSTS700016 — Application not found

```
Application with identifier '<...>' was not found in the directory '...'
```

- Client ID 입력 오타 (vaultwarden 의 GUID 와 Frame MCP 의 GUID 혼동 등)
- 운영자가 새 customer 의 Azure 등록을 아직 안 한 상태

→ 운영자에게 정확한 Client ID 확인 요청.

### AADSTS9010010 — resource/scope mismatch

```
The resource parameter provided in the request doesn't match with the requested scopes
```

운영자 측 Azure 설정 문제. Application ID URI 와 scope URI prefix 가 다를 때 발생. → 운영자 측에서 처리, 직원 작업 X.

### AADSTS7000218 — missing client_secret

```
The request body must contain the following parameter: 'client_assertion' or 'client_secret'
```

- claude.ai 의 Advanced 에 **OAuth Client Secret 미입력**
- 또는 Azure 측 "Allow public client flows" 가 No 상태인데 secret 없음

→ Advanced 칸에 운영자가 준 secret 입력. secret 분실했으면 운영자에게 재요청.

### Bitwarden Send URL — "This Send has been deleted" / "Send not found"

운영자가 Teams DM 으로 보낸 1회용 URL 을 클릭했는데 위 메시지 나옴.

- **1회 클릭 이미 소진** — `-a 1` 설정이라 누군가 (운영자 본인 검증 포함) 이미 1회 열었으면 즉시 무효
- **1일 만료 (`-d 1`)** 경과 — 운영자가 발사한 시각 + 24h 지남
- **운영자가 수동 삭제** (`bw send delete`)

→ 운영자에게 재발급 요청: 본인 이메일 + 어느 서비스 (Blueprint / Hive / Frame) 인지 명시. 운영자 1 명령 (`axe secret send <ENV> --service <svc> --to <local-part>`) + broadcast-dm 으로 새 URL 즉시 송부. 절차: [/architecture/secrets § 사람에게 전달](/architecture/secrets#사람에게-전달--bitwarden-send).

### AADSTS65001 — user/admin consent 없음

```
The user or administrator has not consented to use the application
```

- 첫 로그인 시 동의 화면에서 **Accept** 안 누름
- 또는 admin consent 가 필요한 scope 이지만 미부여

→ 다시 connect 시도, 동의 화면 나오면 Accept 클릭. 안 나오면 운영자 호출.

### AADSTS50011 — redirect URI mismatch

```
The reply URL specified in the request does not match the reply URLs configured
```

운영자 측 Azure 설정 문제 (redirect_uri 누락). → 운영자 작업.

## "mcp_client_invalid"

Anthropic 이 Microsoft 에서 받은 토큰을 frame 에 못 보냄. URL 바의 `entra_aadsts_code=` 확인.

URL 형식: `claude.ai/customize/connectors?...&error_code=mcp_client_invalid&entra_aadsts_code=<코드>&entra_trace_id=&lt;id&gt;`

`entra_aadsts_code` 가 있으면 위 AADSTS 섹션 참조. 없으면 운영자에게 전체 URL 전달.

## "SSO 화면 자체가 안 뜸"

- claude.ai connector 가 stale state — 완전 삭제 후 **브라우저 hard refresh (Cmd+Shift+R)** → 재등록
- 또는 시크릿/incognito 창에서 재시도

## Vault (axe.axelabs.ai/vault) — "Log in with SSO" / Identifier 입력 안 보임

Vaultwarden 기본 로그인 페이지는 **이메일 입력이 먼저** 노출됩니다. SSO Identifier 화면으로 바로 가려면:

- 직접 URL: `https://axe.axelabs.ai/vault/#/sso` → "Organization SSO Identifier" 입력 칸 노출 → `AXE` 입력 → "Log In"
- 또는 이메일 입력 화면 하단의 **"Enterprise single sign-on"** 링크 클릭

## Vault — "Your provider does not send email verification status"

전체 오류:
```
Your provider does not send email verification status.
You will need to change the server configuration
(check `SSO_ALLOW_UNKNOWN_EMAIL_VERIFICATION`) to log in.
```

**원인**: Microsoft Entra ID 의 OIDC id_token 에는 `email_verified` claim 이 포함되지 않음. Vaultwarden Timshel fork 의 기본 동작은 검증 실패 → 로그인 거부.

**해소**: **D-ops-24 (2026-05-22)** — `/Users/axe/.axe/vault/docker-compose.yml` 의 `axe-vaultwarden.environment` 에 `SSO_ALLOW_UNKNOWN_EMAIL_VERIFICATION: "true"` 추가 후 `docker compose up -d --force-recreate axe-vaultwarden`. tenant 내부 사용자만 SSO 흐름에 진입하므로 추가 검증 면제 안전.

직원은 본 해소 이후 위 "Identifier 입력 안 보임" 안내대로 재시도.

## "Connected 떴는데 도구 호출이 실패함"

채팅에서 `Frame:list_open_items` 호출 시 "권한 없음" 또는 "Entity not authorized":

- 본인 이메일이 `customers.yaml` 의 `user_entity_map` 에 매핑 안 됨
- 또는 잘못된 entity 명 사용 (`axec` vs `axes`)

→ 운영자에게 entity 매핑 확인 요청.

## "권한 부족" — 분개 등록 실패

```
이 작업은 write 권한이 필요하나 현재 read 만 부여되어 있습니다
```

본인의 role 이 `read` 만 부여된 상태. 운영자에게 권한 상승 요청.

## "토큰 만료" — 며칠 후 갑자기 안 됨

Microsoft access_token 은 기본 60-90분, refresh_token 은 90일. claude.ai 가 자동 갱신하지만, 90일 무사용 시 만료.

→ claude.ai 의 connector 페이지에서 **Re-authorize** 클릭. Microsoft 로그인 1회 → 재활성.

## `axe login` 은 됐는데 `axe <service> …` 가 401 — Blueprint 플랫폼 토큰 (D-axe-idp-1)

[AXE CLI](/services) 의 `axe login`(브라우저 Entra SSO)은 성공해 토큰을 받았는데 `axe frame tools` 등이 401 이면:

- **서비스가 Blueprint 를 아직 신뢰 안 함** — 해당 서비스에 `BLUEPRINT_ISSUER=https://blueprint.axellc.com` 가 설정돼야 `iss=blueprint` 토큰을 수용. unset 이면 그 토큰은 HS256 경로로 빠져 거부됨(의도된 비파괴 기본값). 운영자: 서비스 env(frame 은 `.env.local`)에 추가 후 `docker compose up -d --force-recreate`.
- **`aud` 불일치** — 플랫폼 토큰 `aud` = `https://axe.axelabs.ai`(`BLUEPRINT_AUDIENCE` 기본). 서비스의 `BLUEPRINT_AUDIENCE` 와 같아야 함.
- **email 미매핑** — 토큰은 유효하나 `customers.yaml` `user_entity_map`/`default_entities_by_domain` 에 해당 email 없음 → `USER_NOT_MAPPED`. customers.yaml 에 추가.
- **Blueprint JWKS 도달 불가** — 서비스가 `https://blueprint.axellc.com/.well-known/jwks.json` 를 못 받으면 `OIDC_UNAVAILABLE`(503). 네트워크/터널 확인.

운영자 배포 함정: blueprint DB 는 `prisma migrate deploy` 가 안 먹음(`_prisma_migrations` 부재) → 새 모델은 `prisma db push`(또는 raw SQL). `BLUEPRINT_OIDC_PRIVATE_KEY` 는 env_file 따옴표/개행 문제 회피 위해 **base64 단일라인**.

## 그 외 — 운영자에게 전달할 정보

문제 해결 안 될 때 운영자 (`ai@axellc.com`) 에게 다음 전부 전달:

1. **어떤 작업 도중** 문제 발생했는지 (connector 추가 / tool 호출 / 다른 것)
2. **정확한 오류 메시지** (스크린샷)
3. **URL 바 전체** (특히 `error_code=`, `entra_aadsts_code=`, `entra_trace_id=` 부분)
4. **claude.ai connector 페이지 상태** (Connected / Disconnected / Authorization failed)
5. **(가능하면) Browser DevTools Network 탭** 에서 `login.microsoftonline.com` 으로 가는 요청의 Request URL