Skycloak
공식Skycloak 관리형 Keycloak을 위한 Model Context Protocol 서버입니다. 모든 MCP 클라이언트에서 클러스터, 영역, 애플리케이션, SSO 및 사용자를 관리할 수 있습니다.
Skycloak MCP(으)로 무엇을 할 수 있나요?
- 클러스터 인벤토리 및 업그레이드 — 클러스터를 나열하고, 버전을 확인하며, 최신 버전이 아닌 클러스터의 업그레이드 경로를 확인합니다.
- Realm 및 애플리케이션 관리 — Realm과 애플리케이션을 생성하거나 업데이트하고, 역할을 할당하며, 애플리케이션 클라이언트 시크릿을 교체합니다.
- ID 공급자 설정 — Realm에 OIDC ID 공급자를 추가하고, 연결을 테스트하며, 기존 SSO 연결을 나열합니다.
- 사용자 및 그룹 관리 — Realm 사용자, 역할, 그룹을 나열한 다음 역할을 할당하거나 사용자를 그룹에 추가합니다.
- 감사 및 이벤트 검토 — 이벤트와 보안 로그를 조회하거나, Realm의 최근 로그인 실패 기록을 소스 IP별로 그룹화해 가져옵니다.
- SIEM 및 웹훅 대상 — SIEM 대상 또는 웹훅 구독을 생성하고, 테스트 이벤트를 전송해 전달 여부를 확인합니다.
문서
skycloak-mcp
Skycloak(관리형 Keycloak)용 공식 Model Context Protocol 서버입니다. 모든 MCP 클라이언트(Claude Desktop, Claude Code, Cursor)에서 클러스터, 영역, 애플리케이션 및 SSO를 관리할 수 있습니다.
상태: 초기 릴리스입니다. 도구 지원 범위가 확대되고 있습니다. 사용 가능한 기능은 변경 로그를 참조하세요.
빠른 시작
claude mcp add --transport http skycloak https://mcp.skycloak.io
API 키, 클라이언트 ID, 구성은 필요하지 않습니다. 브라우저가 열리면 Skycloak에 로그인하고 도구가 표시됩니다. 스트리밍 가능한 HTTP를 지원하는 모든 MCP 클라이언트에서 동일하게 작동합니다. URL만 입력하면 됩니다.
그런 다음 원하는 작업을 요청하세요.
- "내 Keycloak 클러스터 중 업그레이드가 지연된 클러스터는 무엇인가요?"
- "EU 클러스터에 Google 및 GitHub 로그인을 사용하는 스테이징 영역을 만들어 주세요."
- "지난주에 프로덕션 영역에 추가된 사용자는 누구인가요?"
- "관리자 이벤트를 Datadog 웹훅으로 전달하는 SIEM 대상을 설정해 주세요."
인증 및 안전
- OAuth를 사용하는 호스팅 HTTP(구성할 자격 증명 없음). 헤더 없이 클라이언트에서
https://mcp.skycloak.io을 지정하세요. 서버는 RFC 9728 메타데이터를 가리키는401를/.well-known/oauth-protected-resource에서 반환합니다. 클라이언트는 Skycloak 로그인 영역에서 브라우저 인증 코드 흐름을 실행하고, 받은 액세스 토큰을 세션에서 사용할 단기 워크스페이스 범위 API 키로 교환합니다. 키는 한 시간 동안 유효하며 자동으로 갱신됩니다. 클라이언트 구성에는 아무것도 저장되지 않습니다. - API 키를 사용하는 호스팅 HTTP. Skycloak 대시보드에서 키를 만들고
Authorization: Bearer <key>(또는API-Key: <key>)으로 전송하세요. 각 요청에는 자체 자격 증명이 포함되며 해당 자격 증명의 워크스페이스에서만 동작합니다. 서버는 세션 상태를 저장하지 않으므로 요청이 다른 호출자의 자격 증명을 상속하지 않습니다. 키는 사용 전에 검증되지 않습니다. 권한을 확인하는 주체는 Skycloak API이므로, 잘못된 키는 연결 시점이 아니라 첫 도구 호출에서401로 표시됩니다. - 도구는 사용자 역할에 맞춰 제공됩니다. OAuth를 사용하면 세션의 범위에서 허용하는 도구만 목록에 표시되므로, 읽기 전용 워크스페이스 구성원에게는
403에 응답할 쓰기 도구가 표시되지 않습니다. API 키를 사용하면 키의 범위를 서버에서 확인할 수 없으므로 전체 도구가 등록되며, 권한이 없는 호출은 API에서403로 표시됩니다. - 로컬 stdio.
skycloak-mcp init을 실행하고 브라우저에서 승인하세요(OAuth 2.0 장치 인증 흐름). 워크스페이스 범위 API 키를 발급해 운영 체제 키체인에 저장하고 기본 워크스페이스를 자동으로 감지합니다(다른 워크스페이스를 선택하려면--workspace <id>을 전달하세요).skycloak-mcp logout은 저장된 키를 삭제합니다. - 헤드리스 / CI. 브라우저를 완전히 건너뛰려면
SKYCLOAK_API_KEY환경 변수를 설정하세요(Skycloak 대시보드에서 키를 만드세요). 이 변수는 항상 키체인보다 우선합니다. - 쓰기 권한은 플래그가 아니라 자격 증명으로 제어됩니다.
https://mcp.skycloak.io의 호스팅 서버는 쓰기 기능을 지원하며, 실제로 변경할 수 있는 범위는 키의 권한 범위와 워크스페이스 역할에 따라 제한됩니다. 읽기 전용 구성원은 도구 목록에 무엇이 표시되든 어떤 것도 변경할 수 없습니다. 세션에서 읽기 전용 도구만 표시하려면 URL에?readonly=true을 추가하세요. 반대로 로컬 바이너리는--allow-writes로 시작하지 않으면 쓰기 도구를 등록하지 않습니다. - 클러스터 자격 증명은 선택 사항입니다.
get_cluster_credentials은 클러스터의 Keycloak 관리자 자격 증명을 반환하며, 키를 보유한 어시스턴트가 이를 보게 됩니다. 따라서init은 기본적으로 해당 범위를 요청하지 않습니다. 해당 범위가 포함된 키를 사용하세요. 대시보드에서 키를 만들거나 stdio를 통해skycloak-mcp init --allow-credentials로 로그인하세요. 해당 범위가 없으면 두 가지 방법을 안내하는 403 오류가 반환됩니다. - 파괴적인 도구는 확인이 필요합니다. 예를 들어 영역을 삭제하려면 명시적인
confirm=true인수가 필요합니다. - 요청은 Skycloak 요금제에 따라 속도 제한이 적용됩니다.
429응답이 오면 서버는Retry-After을 표시합니다.
도구
도구는 141개입니다. 읽기 전용 도구 62개와 쓰기 도구 79개입니다. 읽기 전용 도구는 항상 사용할 수 있습니다. 호스팅 서버에서는 쓰기 도구도 등록되며 자격 증명의 권한 범위에 따라 제한됩니다. 로컬 바이너리는 --allow-writes로 시작한 경우에만 쓰기 도구를 등록합니다.
도구 이름에는 skycloak_ 접두사가 붙지만 아래 표에서는 생략했습니다. 따라서 클라이언트에서 list_clusters은 skycloak_list_clusters입니다.
| 영역 | 읽기 전용 | 쓰기 (--allow-writes) |
|---|---|---|
| 클러스터 | list_clusters, get_cluster, list_cluster_locations, list_cluster_types, list_cluster_features, list_cluster_versions, list_cluster_upgrades, get_cluster_upgrade_path, get_cluster_credentials, get_cluster_insights, get_cluster_maintenance_window | create_cluster, update_cluster, delete_cluster, cancel_cluster_upgrade, restart_cluster_instances, set_cluster_maintenance_window, delete_cluster_maintenance_window |
| 엣지 보안 | get_cluster_security, list_cluster_captcha_domains | update_cluster_security, add_cluster_captcha_domain, remove_cluster_captcha_domain |
| 영역 | list_realms, get_realm | create_realm, update_realm, delete_realm |
| 애플리케이션 | list_applications, get_application, list_application_roles, list_application_sessions | create_application, update_application, delete_application, assign_application_role, remove_application_role, rotate_application_secret |
| ID 공급자 | list_identity_providers, get_identity_provider, list_identity_provider_templates, discover_oidc | create_identity_provider (OIDC), update_identity_provider, delete_identity_provider, test_identity_provider |
| 사용자, 역할 및 그룹 | list_realm_users, get_realm_user, list_realm_roles, get_realm_role, list_realm_groups, get_realm_group, list_realm_group_members, list_user_roles, list_user_groups | create_realm_user, update_realm_user, delete_realm_user, create_realm_role, update_realm_role, delete_realm_role, create_realm_group, update_realm_group, delete_realm_group, assign_realm_user_role, remove_realm_user_role, add_realm_user_to_group, remove_realm_user_from_group |
| 사용자 지정 도메인 | list_domains, get_domain, list_domain_routes, get_domain_route | create_domain, verify_domain, delete_domain, create_domain_route, update_domain_route, delete_domain_route |
| 브랜딩 및 테마 | list_themes, get_theme, get_theme_assignment, get_client_theme_assignment, get_login_branding, get_email_branding, download_theme_content, get_theme_settings | set_theme_assignment, set_client_theme_assignment, update_theme, update_theme_content, update_theme_settings, delete_theme, upsert_login_branding, delete_login_branding, upsert_email_branding, delete_email_branding |
| 확장 기능 | list_extensions, list_cluster_extensions | install_extension, upgrade_extension, update_extension, uninstall_extension, delete_extension |
| SMTP | get_smtp | upsert_smtp, delete_smtp, test_smtp |
| 내보내기 및 로그 | list_exports, get_export, get_logs, get_security_logs, query_events | create_export, delete_export, export_cluster_events |
| 영역 가져오기 및 내보내기 | get_realm_export, get_realm_import | create_realm_export, create_realm_import, create_realm_import_upload_url |
| SIEM | list_siem_destinations, get_siem_destination | create_siem_destination, update_siem_destination, delete_siem_destination, test_siem_destination |
| 웹훅 | list_webhook_event_types, list_webhook_subscriptions, get_webhook_subscription | create_webhook_subscription, update_webhook_subscription, delete_webhook_subscription, test_webhook_subscription |
| OpenFGA | list_openfga_instances, get_openfga_instance | create_openfga_instance, delete_openfga_instance |
규칙: 파괴적인 도구(delete_*, uninstall_extension, cancel_cluster_upgrade, update_theme_content, update_theme_settings, restart_cluster_instances)에는 confirm=true이 필요합니다. update_theme_settings은 워크스페이스에서 exact_theme_names을 켜거나 끕니다. 호출자의 API 키는 워크스페이스 소유자 또는 관리자를 위해 발급된 것이어야 합니다. 그렇지 않으면 themes:write이 있어도 403이 반환됩니다. 이 기능을 켜면 기존 테마가 백그라운드에서 정확한 제공 이름으로 이동됩니다. 정확한 이름으로 콘텐츠가 교체된 테마는 restart_cluster_instances이 해당 클러스터의 Keycloak 인스턴스를 롤링할 때까지 get_theme/list_themes/update_theme_content에서 restart_required: true를 보고합니다. 재시작은 즉시 적용하는 대신 클러스터의 유지 관리 시간까지 연기될 수 있으며, 이 경우 deferred: true 및 알려진 경우 next_window로 보고됩니다. create_cluster은 비동기 작업입니다. 클러스터가 available이 될 때까지 get_cluster을 폴링하세요. create_domain는 고객이 생성해야 하는 DNS 레코드를 반환하고, verify_domain은 DNS 확인을 시작합니다. set_theme_assignment는 Keycloak 테마 유형별로 사용자 지정 테마를 활성화합니다(빈 문자열은 기본 제공 테마로 재설정합니다). update_theme_content는 테마의 아카이브를 제자리에서 교체합니다(content_base64의 base64 ZIP 또는 Keycloakify JAR). 테마의 ID, 이름, 영역 및 애플리케이션 할당은 유지되므로 테마를 수정할 때 더 이상 삭제 후 다시 업로드할 필요가 없습니다. 덮어쓴 아카이브는 복구할 수 없으므로 confirm=true이 필요합니다. update_theme은 여전히 이름, 설명 및 버전만 변경합니다. 호출 방법은 docs/theme-content-update.md를 참조하세요. update_cluster_security는 CAPTCHA 설정을 변경하지 않습니다. 영역 가져오기/내보내기는 한 영역의 구성을 이동하며, 전체 클러스터 데이터베이스를 덤프하는 create_export과는 별개입니다. 둘 다 비동기 작업이며 영역 아카이브는 항상 암호화되므로, 내보내기에 사용한 비밀번호가 있어야 다시 가져올 수 있습니다. 기존 내보내기 파일(source_export_id)에서 바로 영역을 가져오거나 업로드한 아카이브(create_realm_import_upload_url, PUT, 이후 upload_s3_key)에서 가져올 수 있습니다. 가져오기는 영역을 생성하며 이름이 충돌하면 덮어쓰지 않고 거부합니다. 사용자와 자격 증명도 함께 가져오므로 confirm=true이 필요합니다.
OpenFGA 인스턴스: 모든 OpenFGA 도구에는 cluster_id가 필요합니다. create_openfga_instance은 OpenFGA 인스턴스를 클러스터의 realm 하나에 연결합니다. 각 영역에는 최대 하나의 인스턴스만 연결할 수 있습니다. 워크스페이스 요금제에 OpenFGA가 포함되지 않았거나 인스턴스 한도에 도달한 경우 403, 해당 영역에 이미 인스턴스가 있는 경우 409, 영역이 master이거나 존재하지 않거나 비활성화된 경우 422을 반환합니다. 비동기 작업이므로 status이 ready 또는 failed가 될 때까지 get_openfga_instance를 폴링하세요. 인스턴스는 해당 영역에서 발급되고 대상(audience)을 포함하는 토큰만 허용합니다. get_openfga_instance은 호출에 필요한 api_url, issuer 및 audience를 반환합니다. 영역 토큰에 대상을 추가하는 대상 매퍼는 Keycloak에 추가됩니다. OpenFGA 액세스 권한이 없어도 목록 조회와 삭제는 가능합니다. delete_openfga_instance은 배포, 경로 및 데이터베이스를 제거하며, 그 안의 권한 부여 데이터는 복구할 수 없습니다. 인스턴스가 완전히 제거될 때까지 deleting로 표시됩니다.
클러스터 위치: create_cluster의 location 및 list_clusters, get_cluster, list_cluster_locations이 반환하는 값은 대소문자와 관계없이 us(미국 동부), us-west(미국 서부), ca(캐나다), eu(유럽) 또는 au(호주) 중 하나입니다. us는 항상 미국 동부를 의미합니다. us-west은 해당 위치에 대한 액세스 권한을 부여받은 워크스페이스에서만 사용할 수 있습니다. list_cluster_locations는 워크스페이스에서 available가 설정된 모든 위치를 나열합니다. 사용할 수 없는 위치에 클러스터를 만들면 API에서 400 "location not available"을 반환합니다.
프롬프트
8개의 프롬프트가 도구를 활용하기 위한 시작점을 제공합니다. 클라이언트에서는 슬래시 명령이나 추천 작업으로 표시됩니다. 각 프롬프트는 인수(영역, 클러스터, 시간 범위)를 받아 모델이 올바른 도구를 올바른 순서로 사용하도록 안내합니다.
| 프롬프트 | 기능 |
|---|---|
audit_self_registration | 하나의 클러스터 또는 모든 클러스터에서 셀프 등록을 허용하는 realm을 모두 찾습니다 |
review_upgrades | Keycloak 버전이 뒤처진 클러스터를 찾아 업그레이드 경로를 제시합니다 |
triage_failed_logins | realm의 최근 로그인 실패 기록을 가져와 소스 IP별로 그룹화합니다 |
review_identity_providers | realm의 SSO 연결을 나열하고 특정 연결이 활성화되어 있는지 확인합니다 |
review_admin_changes | 최근 realm에서 누가 무엇을 변경했는지, 특히 로그인 및 보안 설정을 중심으로 보여줍니다 |
provision_environment | 클러스터를 만들고 realm을 추가한 다음 ID 공급자를 연결하고 각 단계를 확인합니다 |
set_up_custom_domain | 사용자 지정 도메인을 추가하고 정확한 DNS 레코드를 제공한 뒤 확인하고 realm으로 라우팅합니다 |
rotate_client_secret | 애플리케이션의 클라이언트 시크릿을 재생성하기 전에 영향 범위를 명확히 설명합니다 |
프롬프트는 이름에 언급된 도구와 동일한 방식으로 제한됩니다. 변경 작업을 수행하는 세 가지 프롬프트는 참조하는 쓰기 도구를 호출할 수 있는 세션에만 제공되며, 지침은 변경 전에 사용자에게 확인하도록 모델에 안내합니다. 파괴적 도구에 대한 confirm=true 요구 사항도 계속 적용됩니다.
스킬
프롬프트가 시작점이라면 스킬은 모델이 필요할 때 불러오는 완전한 운영 플레이북입니다. 서버는 초안 SEP-2640 Skills 확장을 통해 네 가지 스킬을 제공합니다. 이 확장은 기능에 io.modelcontextprotocol/skills을 선언하고, skills/list 및 skills/get에 응답하며, 각 SKILL.md을 목록 항목에 sha256 다이제스트를 포함한 일반 리소스로 skill://<name>/SKILL.md에서 제공합니다. OpenAI의 플러그인 디렉터리는 정확히 이 형식으로 스킬을 가져옵니다.
| 스킬 | 설명 |
|---|---|
auth-incident-triage | "사용자가 로그인할 수 없음" 문제를 분류합니다. 이벤트, WAF 로그, 클러스터 상태를 사용해 플랫폼 장애와 공격, 구성 변경을 구분합니다. 읽기 전용 |
enterprise-sso-rollout | 엔터프라이즈 IdP를 realm에 처음부터 끝까지 연결합니다. 발급자 검증, 업스트림 앱 등록, 브로커 구성, 연결 테스트, 실제 로그인 이벤트를 통한 검증을 포함합니다 |
keycloak-migration-doctor | 지원팀에서 실제로 확인하는 차단 요인(스크립트 정책, 기존 /auth 경로, 부분 내보내기 관련 예상 사항)을 기준으로 Keycloak 내보내기, 가져오기 또는 마이그레이션을 사전 점검하고, 일반적인 대시보드 알림 대신 실제 error_message을 읽어 실패한 작업을 진단합니다 |
keycloak-upgrade-readiness | 버전 차이를 평가하고 새 Keycloak 버전에서 발생하는 문제(확장 기능, 테마)를 파악한 뒤, 롤백 계획으로 내보내기를 사용해 환경 전반의 롤아웃 순서를 정합니다 |
스킬은 이름에 언급된 도구와 동일한 방식으로 제한됩니다. 쓰기 도구를 기반으로 하는 세 가지 워크플로는 읽기 전용 세션에 제공되지 않으며, 범위가 지정된 세션에는 실제로 사용할 수 있는 도구만 포함된 스킬이 제공됩니다. 소스는 표준 Agent Skills 형식으로 internal/tools/skills/에 스킬별 디렉터리로 저장되어 있으므로, 로컬 스킬 디렉터리에 그대로 복사해 사용할 수도 있습니다.
연결
호스팅 HTTP의 경우 가장 간단한 방법은 OAuth이며, 자격 증명이 필요하지 않습니다.
claude mcp add --transport http skycloak https://mcp.skycloak.io
첫 호출 시 브라우저가 열립니다. Skycloak 로그인 페이지에서 승인하면 도구가 표시됩니다. 둘 이상의 워크스페이스에 속해 있다면 사용할 워크스페이스를 지정하세요.
claude mcp add --transport http skycloak "https://mcp.skycloak.io?workspace=<workspace-id>"
그렇지 않으면 Skycloak 대시보드에서 API 키를 만들고 MCP 클라이언트가 해당 키를 bearer token으로 보내도록 구성하세요.
claude mcp add --transport http skycloak https://mcp.skycloak.io --header "Authorization: Bearer sk_sc_XXX"
그러면 .claude.json에 다음 항목이 추가됩니다.
{
"mcpServers": {
"skycloak": {
"type": "http",
"url": "https://mcp.skycloak.io",
"headers": {
"Authorization": "Bearer sk_sc_XXX"
}
}
}
}
Gemini CLI는 이 저장소의 매니페스트를 사용해 호스팅 서버를 확장 프로그램으로 설치합니다.
gemini extensions install https://github.com/sky-cloak/skycloak-mcp
Antigravity는 plugins/skycloak/의 번들을 사용해 호스팅 서버를 플러그인으로 설치합니다.
agy plugin install ./plugins/skycloak
Copilot CLI는 저장소 루트의 Agent Plugins 매니페스트에서 목록을 승인한 후 설치합니다.
copilot plugin install skycloak@awesome-copilot
로컬 stdio의 경우 한 번 로그인한 다음 클라이언트가 skycloak-mcp run을 가리키도록 설정하세요.
skycloak-mcp init # one-time browser sign-in; stores a key in your keychain
Claude Desktop / Cursor (로컬, stdio):
{
"mcpServers": {
"skycloak": {
"command": "skycloak-mcp",
"args": ["run", "--transport", "stdio"]
}
}
}
Claude Code:
claude mcp add skycloak -- skycloak-mcp run --transport stdio
헤드리스/CI 환경(브라우저 없음)에서는 init을 건너뛰고 대신 키를 전달하세요. 구성에 "env": { "SKYCLOAK_API_KEY": "sk_sc_..." }을 추가하거나 claude mcp add skycloak --env SKYCLOAK_API_KEY=sk_sc_... -- skycloak-mcp run --transport stdio을 사용하세요.
변경하려는 경우에만 --allow-writes을 추가하세요( skycloak-mcp init --allow-writes으로 로그인하거나 쓰기 범위 키를 사용).
호스팅 HTTP URL에 ?readonly=true을 추가하면 해당 HTTP 세션에서 읽기 전용 도구만 노출되고, ?readonly=false을 추가하면 쓰기 가능한 도구를 요청합니다. 쿼리 매개변수의 기본값은 false이지만, 서버가 --allow-writes으로 시작된 경우에만 쓰기 도구가 등록됩니다.
?workspace=<uuid>을 추가하면 OAuth 세션에서 사용할 워크스페이스를 선택할 수 있습니다. 둘 이상의 워크스페이스에 속한 경우에만 필요합니다. 워크스페이스가 하나뿐이면 서버가 자동으로 선택하며, 여러 워크스페이스에 속해 있으면서 아무것도 지정하지 않으면 목록을 표시하는 메시지와 함께 연결이 실패합니다.
HTTP 전송 실행
skycloak-mcp run --transport http --http-addr :8080
자체 자격 증명은 필요하지 않습니다. 호출자가 요청마다 자격 증명을 제공하므로 배포 시 주입할 항목이 없습니다. GET /healthz 및 GET /readyz는 인증 없이 프로세스가 실행 중인지 여부만 보고합니다. 의도적으로 Skycloak API를 확인하지 않으므로 업스트림 장애가 모든 복제본의 프로브를 동시에 실패하게 만들지 않습니다. 서버는 세션 상태를 보유하지 않으므로 복제본에 세션 고정이 필요 없으며 자유롭게 확장하거나 롤링할 수 있습니다. SIGTERM은 새 연결을 중단하고 진행 중인 호출을 마무리합니다.
SKYCLOAK_ISSUER 및 SKYCLOAK_DASHBOARD_URL이 설정되어 있으면 OAuth 경로가 활성화되며, 기본적으로 설정되어 있습니다. 이때 GET /.well-known/oauth-protected-resource은 인증 없이 제공되며 realm을 인증 서버로 지정합니다. resource 값은 설정된 경우 SKYCLOAK_PUBLIC_URL에서 가져오고, 그렇지 않으면 요청 자체의 Host 및 스킴에서 가져옵니다. 따라서 인그레스 뒤에 단일 호스트를 배포할 때는 추가 구성이 필요하지 않습니다. 스킴은 X-Forwarded-Proto이 있으면 해당 값을 사용하고, 그렇지 않으면 루프백 호스트가 아닌 경우 https을 기본값으로 사용합니다. TLS는 업스트림에서 종료되므로 http:// 식별자를 게시하면 클라이언트가 연결한 URL과 일치하지 않기 때문입니다. 인그레스가 Host을 다시 쓰는 경우 SKYCLOAK_PUBLIC_URL을 설정하세요. 문서에는 openid profile email도 scopes_supported으로 나열되며, WWW-Authenticate 챌린지는 이를 scope 매개변수로 반복합니다. 따라서 둘 중 하나를 읽는 클라이언트는 realm에 해당 항목을 요청합니다. openid은 필수입니다. 토큰 교환 과정에서 대시보드가 Keycloak의 userinfo 엔드포인트를 호출하며, Keycloak은 해당 항목 없이 발급된 토큰을 거부하기 때문입니다. 해당 항목 없이 도착한 토큰은 성공할 수 없는 교환으로 전달되지 않고, 검증 단계에서 401 및 챌린지와 함께 거부됩니다. 따라서 이전에 발급받은 토큰을 보유한 클라이언트는 재시도를 멈추고 다시 로그인합니다. 발급자 또는 대시보드 변수 중 하나라도 비우면 OAuth가 완전히 꺼지고, 서버는 API 키만 요청하는 방식으로 돌아갑니다.
OPENAI_APPS_CHALLENGE_TOKEN은 OpenAI 플러그인 디렉터리의 도메인 확인 토큰을 /.well-known/openai-apps-challenge에서 일반 텍스트로만 제공합니다. 설정하지 않으면 경로가 등록되지 않고 404를 반환합니다.
시작 시 해결된 연결 설정(oauth=, issuer=, dashboard=, public_url=, endpoint=, allow_writes=)을 한 줄로 기록하므로 재배포 없이도 잘못 구성된 배포를 파악할 수 있습니다. OAuth 경로에서 거부된 각 요청은 실패한 단계(verify, exchange 또는 scopes), 호출자에게 반환된 상태 코드, 근본 오류를 한 줄로 기록합니다. 검증 실패에는 토큰을 거부한 검사 항목(expired, wrong_issuer, bad_signature, unknown_key_id, wrong_token_type, no_openid_scope 등)이 추가되고, 교환 실패에는 대시보드의 상태 코드와 호출한 호스트가 추가됩니다. 토큰이 검증된 후에는 호출자가 토큰의 subject로 표시되며, 자격 증명으로 표시되지는 않습니다. 액세스 토큰, Authorization 헤더, 발급된 API 키는 절대 로그에 기록되지 않습니다.
서버가 Skycloak API에 보내는 항목
호스팅 서버와 로컬 바이너리는 Skycloak API에 동일한 헤더를 보냅니다(SKYCLOAK_ENDPOINT).
| 헤더 | 값 | 용도 |
|---|---|---|
API-Key | API 키 또는 세션에서 발급된 키 | 요청을 인증합니다 |
API-Version | SKYCLOAK_API_VERSION | 서버가 빌드된 API 계약을 고정합니다 |
User-Agent | skycloak-mcp/<version> | 클라이언트를 식별합니다 |
X-MCP-Tool | 도구에 등록된 이름(예: skycloak_list_realms) | 요청을 보낸 도구를 나타냅니다 |
X-MCP-Call-Id | 도구 호출마다 한 번 생성되는 임의의 UUID | 한 호출에 속한 모든 요청을 그룹화합니다 |
X-MCP-Tool 및 X-MCP-Call-Id은 도구 호출을 처리하는 동안에만 전송됩니다. 한 번의 호출에서 여러 요청이 발생할 수 있습니다. cluster_id이 생략되면 클러스터마다 한 번씩 요청하고, 429 또는 5xx을 재시도할 때도 요청할 수 있으며, 모든 요청은 호출 ID를 공유합니다. Skycloak은 이 쌍을 사용해 각 도구의 사용 빈도를 집계하고, 이를 바탕으로 개선하거나 문서화하거나 폐기할 도구를 결정합니다. 이 헤더에는 인수, 결과 또는 API 키로 이미 식별되는 정보 외에 사용자에 관한 정보가 포함되지 않습니다. 또한 Keycloak 클러스터가 아닌 Skycloak API에만 전송됩니다. 로그인 및 API 키 발급처럼 도구 호출 외부에서 이루어지는 요청에는 두 헤더가 모두 포함되지 않습니다.
구성
| 환경 변수 | 기본값 |
|---|---|
SKYCLOAK_API_KEY | 없음(stdio에서는 선택 사항, HTTP 클라이언트는 대신 API-Key 헤더를 제공) |
SKYCLOAK_ENDPOINT | https://api.skycloak.io |
SKYCLOAK_API_VERSION | 현재 API 버전 |
SKYCLOAK_ISSUER | https://login.app.skycloak.io/realms/skycloak (CLI 로그인 및 HTTP 전송이 토큰을 검증하는 인증 서버) |
SKYCLOAK_CLIENT_ID | skycloak-mcp (CLI 기기 인증 흐름에만 사용) |
SKYCLOAK_DASHBOARD_URL | https://app.skycloak.io (CLI 키 및 HTTP 세션 키 발급) |
SKYCLOAK_PUBLIC_URL | 없음(각 요청에서 파생됨. 인그레스가 Host을 다시 쓰는 경우 설정) |
OPENAI_APPS_CHALLENGE_TOKEN | OpenAI 플러그인 디렉터리 확인 토큰을 /.well-known/openai-apps-challenge에서 제공합니다. 설정하지 않으면 해당 경로는 404를 반환합니다. |
명령: init (브라우저 로그인), run (서버 실행), logout (저장된 키 제거). init은 --workspace <id>, --allow-writes, --allow-credentials, --ttl-days을 허용합니다(기본값 90).
| 플래그 | 기본값 | 설명 |
|---|---|---|
--transport | stdio | stdio 또는 http |
--http-addr | :8080 | HTTP 전송의 수신 주소 |
--allow-writes | false | stdio에서 변경 도구를 활성화하고, readonly=false을 사용하는 HTTP 세션에서 쓰기 도구를 등록할 수 있도록 허용합니다 |
개발
make build # build the server binary
make test # unit tests
make run # run on stdio for local testing
make inspector # MCP Inspector against the local binary
make lint # golangci-lint
make generate # regenerate the API client from the OpenAPI spec
internal/apiclient 아래의 API 클라이언트는 oapi-codegen을 사용해 Skycloak OpenAPI 사양에서 생성됩니다.
API와 동기화 유지
internal/apiclient의 클라이언트는 oapi-codegen을 사용해 internal/apiclient/openapi.yaml에서 생성됩니다. 새로 생성하려면 make generate을 실행하세요. 커밋된 생성 코드가 사양과 달라지면 CI가 실패합니다. 요청은 429/5xx에서 재시도되며, Retry-After을 고려한 백오프가 적용됩니다.
배포
각 태그마다 GitHub 바이너리와 ghcr.io/sky-cloak/skycloak-mcp 컨테이너 이미지로 릴리스되며, MCP Registry에 io.skycloak/skycloak-mcp으로 게시됩니다. 대부분의 사용자는 둘 다 필요하지 않습니다. 호스팅 서버는 설치할 필요가 없습니다.
플러그인 번들
plugins/skycloak/은 두 클라이언트에서 사용할 수 있는 단일 폴더입니다. Antigravity용 .antigravity-plugin/plugin.json 및 mcp_config.json, Claude용 .claude-plugin/plugin.json을 제공합니다. 두 클라이언트 모두 호스팅 서버를 가리키며 네 가지 스킬을 포함합니다. 설치 프로그램은 해당 폴더만 받으므로 스킬은 internal/tools/skills/의 바이트 단위 복사본입니다.
저장소 루트의 plugin.json 및 mcp.json는 GitHub의 awesome-copilot 마켓플레이스에서 읽는 Agent Plugins v1.0.0 매니페스트입니다. 해당 형식에는 로고 필드가 없으므로, 목록의 로고는 extensions["com.github.copilot"]에 지정되어 있습니다.
해당 매니페스트와 .grok-plugin/plugin.json의 version 필드는 CI에서 릴리스 태그를 기준으로 설정됩니다. 디렉터리 목록은 main를 추적하기 때문입니다. 플러그인 README의 디렉터리 업데이트 섹션에 설명되어 있습니다.
보안
취약점은 비공개로 신고해 주세요. SECURITY.md를 참조하세요.
기여자
Skycloak에서 Guilliano Molaire, Neville Omangi, Aphilas가 만들었습니다. 저장소를 공개할 때 기록을 하나로 합쳤으므로, 커밋 로그만으로는 누가 어떤 작업을 했는지 알 수 없습니다.
라이선스
Apache-2.0. internal/apiclient/openapi.yaml의 OpenAPI 설명은 Skycloak
플랫폼 API에서 생성되며 저작권은 Skycloak에 있습니다. 클라이언트를 생성하고 검증할 수 있도록 여기에 포함했습니다. NOTICE를 참조하세요.