Skip to Content
직원 온보딩문제 해결

문제 해결

”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 확인:

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 정상.

검증 명령:

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) 의 schema discovery 가 MCP 토큰 인증 필요. 토큰 없이 호출 시 일반 MCP 호출과 동일 401.

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

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 § 사람에게 전달.

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 의 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 단일라인.

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

문제 해결 안 될 때 운영자 ([email protected]) 에게 다음 전부 전달:

  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
Last updated on
Vault setup (KDF + 4 client)고객사 IT 가이드