AlphaKey MCP Server

알파키(AlphaKey) IDaaS 관리 API를 AI 코딩 도구에서 대화형으로 호출할 수 있는 MCP(Model Context Protocol) 서버입니다.

130개 도구 제공: 읽기 63개 + 쓰기 67개 (확인 게이트 포함)

지원 도구: Kiro, VS Code + GitHub Copilot, Cursor, Windsurf, Claude Desktop, Cline

---

설치 가이드 (처음부터 끝까지)

STEP 1. uv 설치 (1회만)

터미널을 열고 아래 한 줄을 복사해서 실행하세요.

Mac/Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

설치 확인:

uv --version

→ 버전 번호가 나오면 성공

---

STEP 2. GitHub SSH 연결 확인 (1회만)

이 서버는 현재 private 레포이므로 GitHub SSH 인증이 필요합니다.

ssh -T git@github.com

✅ Hi 사용자명! You've successfully authenticated 나오면 OK

❌ Permission denied 나오면:

1. SSH 키 생성: ssh-keygen -t ed25519 -C "내이메일@lguplus.co.kr"
2. 공개키 복사: cat ~/.ssh/id_ed25519.pub
3. GitHub > Settings > SSH and GPG keys > New SSH key에 붙여넣기
4. 다시 ssh -T git@github.com 확인

---

STEP 3. 알파키 API 토큰 준비

알파키 관리자 콘솔에서 토큰을 발급받으세요.

1. 알파키 관리자 콘솔 접속 (https://회사명.alphakey.kr)
2. 설정 및 관리 > OpenAPI 토큰 관리
3. 토큰 발급 클릭
4. 발급된 토큰 복사해두기

---

STEP 4. MCP 설정 파일 편집

사용하는 도구에 따라 아래 파일을 열어주세요.

도구	파일 위치	여는 방법
Kiro	프로젝트 폴더/.kiro/settings/mcp.json	Kiro에서 프로젝트 열고 파일 생성
Claude Desktop (Mac)	~/Library/Application Support/Claude/claude_desktop_config.json	Finder에서 Cmd+Shift+G → 경로 붙여넣기
VS Code + Copilot	프로젝트 폴더/.vscode/mcp.json	VS Code에서 파일 생성
Cursor	프로젝트 폴더/.cursor/mcp.json	Cursor에서 파일 생성

파일이 없으면 새로 만드세요. 폴더도 없으면 폴더부터 만드세요.

---

STEP 5. 아래 내용을 복사해서 붙여넣기

{
  "mcpServers": {
    "alphakey": {
      "command": "uvx",
      "args": ["--from", "git+ssh://git@github.com/lgu-idaas/alphakey-mcp-server", "alphakey-mcp-server"],
      "env": {
        "ALPHAKEY_BASE_URL": "https://여기에_회사_테넌트_URL",
        "ALPHAKEY_TOKEN": "여기에_발급받은_토큰"
      }
    }
  }
}

두 군데만 수정하세요:

• 여기에_회사_테넌트_URL → 예: https://lguplus.alphakey.kr
• 여기에_발급받은_토큰 → STEP 3에서 복사한 토큰

저장하세요.

---

STEP 6. 도구 리로드

도구	리로드 방법
Kiro	Cmd+Shift+P → Reload Window
Claude Desktop	완전 종료 후 재시작
VS Code	Cmd+Shift+P → Reload Window
Cursor	Cmd+Shift+P → Reload Window

---

STEP 7. 테스트

AI 채팅에서 아래를 입력해보세요:

알파키 사용자 목록 보여줘

사용자 목록이 나오면 설치 성공! 🎉

---

문제 해결

증상	원인	해결
uv: command not found	uv 미설치	STEP 1 다시 실행
Permission denied (publickey)	SSH 키 미등록	STEP 2 진행
인증 오류 / 응답 없음	토큰 만료 또는 IP 제한	관리자 콘솔에서 토큰 재발급
도구에서 MCP 서버 안 보임	설정 파일 경로 오류	STEP 4의 파일 위치 재확인
JSON 파싱 에러	JSON 문법 오류	쉼표, 중괄호 누락 확인

---

환경변수

변수	필수	설명
ALPHAKEY_BASE_URL	✅	알파키 테넌트 URL
ALPHAKEY_TOKEN	✅	관리자 콘솔에서 발급받은 API 토큰
SSL_CA_BUNDLE	❌	자체 서명 인증서 사용 시 CA 번들 경로
ALPHAKEY_AUDIT_LOG	❌	감사 로그 경로 (기본: ~/.alphakey/audit.log)
ALPHAKEY_AUDIT_LOG_ENABLED	❌	감사 로그 활성화 (기본: true)

---

보안

• TLS 통신 암호화 (HTTPS 강제)
• 토큰별 IP 제한 + 만료 기간
• 쓰기 작업 2단계 확인 게이트
• 입력값 검증 (ID/IP/날짜/enum)
• 감사 로그 (30일 로테이션)
• 에러 정보 은닉

---

제공 도구 (130개)

사용자/앱/그룹/보안/SSO/MFA/대시보드/프로비저닝/관리자 설정 전 영역을 커버합니다.

자연어로 질문하면 AI가 적절한 도구를 자동으로 호출합니다.

---

사용 예시

사용자 목록 보여줘
Figma 앱 사용자 몇 명이야?
이상 접속 내역 보여줘
감지 정책 목록 조회해줘
새 사용자 등록해줘
SSO 앱 연동 상세 조회해줘

---

라이선스

Copyright © LG유플러스. All rights reserved.

본 소프트웨어는 알파키(AlphaKey) IDaaS 서비스 이용 고객에게 제공됩니다.