Skycloak

skycloak-mcp

Server Model Context Protocol resmi untuk Skycloak (Keycloak terkelola): kelola klaster, realm, aplikasi, dan SSO Anda dari klien MCP mana pun (Claude Desktop, Claude Code, Cursor).

Status: rilis awal. Cakupan alat terus bertambah; lihat changelog untuk mengetahui apa yang tersedia.

Mulai cepat

claude mcp add --transport http skycloak https://mcp.skycloak.io

Tanpa kunci API, tanpa ID klien, tanpa konfigurasi. Browser Anda terbuka, Anda masuk ke Skycloak, dan alat-alatnya muncul. Klien MCP mana pun yang mendukung streamable HTTP bekerja dengan cara yang sama: berikan URL-nya dan tidak ada yang lain.

Lalu minta sesuatu:

• "Klaster Keycloak mana saja yang tertinggal pembaruan?"
• "Buat realm staging di klaster EU dengan masuk melalui Google dan GitHub."
• "Siapa yang ditambahkan ke realm produksi dalam seminggu terakhir?"
• "Siapkan tujuan SIEM yang meneruskan peristiwa admin ke webhook Datadog kami."

Autentikasi & keamanan

• HTTP terhosting, dengan OAuth (tanpa kredensial yang perlu dikonfigurasi). Arahkan klien Anda ke https://mcp.skycloak.io tanpa header. Server menjawab 401 dengan penunjuk ke metadata RFC 9728 di /.well-known/oauth-protected-resource, klien menjalankan alur kode otorisasi browser terhadap realm login Skycloak, dan token akses yang diperoleh ditukar dengan kunci API berumur pendek yang tercakup dalam workspace tempat sesi berjalan. Kunci tersebut bertahan satu jam dan diperbarui secara otomatis. Tidak ada yang disimpan dalam konfigurasi klien Anda.
• HTTP terhosting, dengan kunci API. Buat kunci di dasbor Skycloak dan kirim sebagai Authorization: Bearer <key> (atau API-Key: <key>). Setiap permintaan membawa kredensialnya sendiri dan hanya bertindak sebagai workspace kredensial tersebut. Server tidak menyimpan status sesi, sehingga sebuah permintaan tidak pernah mewarisi pemanggil lain. Kunci tidak diverifikasi sebelum digunakan: API Skycloak adalah otoritasnya, sehingga kunci yang tidak valid muncul sebagai 401 pada panggilan alat pertama, bukan pada saat koneksi.
• Alat sesuai dengan peran Anda. Melalui OAuth, daftar alat dipangkas sesuai dengan cakupan sesi, sehingga anggota workspace hanya-baca tidak diperlihatkan alat tulis yang akan menjawab 403. Dengan kunci API, seluruh permukaan terdaftar, karena cakupan kunci tidak terlihat oleh server, dan panggilan yang tidak sah muncul sebagai 403 dari API.
• Stdio lokal. Jalankan skycloak-mcp init dan setujui di browser Anda (alur otorisasi perangkat OAuth 2.0). Ini membuat kunci API yang tercakup dalam workspace, menyimpannya di keychain sistem operasi Anda, dan mendeteksi workspace default Anda secara otomatis (berikan --workspace <id> untuk memilih yang lain). skycloak-mcp logout menghapus kunci yang tersimpan.
• Headless / CI. Tetapkan variabel lingkungan SKYCLOAK_API_KEY (buat kunci di dasbor Skycloak) untuk melewati browser sepenuhnya. Ini selalu diutamakan daripada keychain.
• Operasi tulis dibatasi oleh kredensial Anda, bukan oleh bendera. Server terhosting di https://mcp.skycloak.io berjalan dengan kemampuan tulis, dan apa yang sebenarnya dapat Anda ubah dibatasi oleh cakupan kunci dan peran workspace Anda: anggota hanya-baca tidak dapat mengubah apa pun, apa pun daftar alatnya. Tambahkan ?readonly=true ke URL untuk memaksa permukaan alat hanya-baca untuk sebuah sesi. Biner lokal justru sebaliknya dan tidak mendaftarkan alat tulis kecuali dijalankan dengan --allow-writes.
• Kredensial klaster bersifat opt-in. get_cluster_credentials mengembalikan kredensial admin Keycloak sebuah klaster, yang akan terlihat oleh asisten yang memegang kunci tersebut, sehingga init tidak meminta cakupan itu secara default. Gunakan kunci yang membawanya: buat di dasbor, atau melalui stdio masuk dengan skycloak-mcp init --allow-credentials. Tanpa itu, alat mengembalikan 403 yang menjelaskan kedua jalur tersebut.
• Alat destruktif memerlukan konfirmasi: menghapus realm, misalnya, memerlukan argumen confirm=true yang eksplisit.
• Permintaan dibatasi lajunya sesuai dengan paket Skycloak Anda; pada respons 429, server menampilkan Retry-After.

Alat

137 alat: 60 hanya-baca dan 77 tulis. Alat hanya-baca selalu tersedia. Di server terhosting, alat tulis juga terdaftar dan dibatasi oleh cakupan kredensial Anda; biner lokal mendaftarkannya hanya saat dijalankan dengan --allow-writes.

Nama alat membawa awalan skycloak_ yang dihilangkan pada tabel di bawah, sehingga list_clusters adalah skycloak_list_clusters di klien Anda.

Area	Hanya-baca	Tulis (--allow-writes)
Klaster	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
Keamanan tepi	get_cluster_security, list_cluster_captcha_domains	update_cluster_security, add_cluster_captcha_domain, remove_cluster_captcha_domain
Realm	list_realms, get_realm	create_realm, update_realm, delete_realm
Aplikasi	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
Penyedia identitas	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
Pengguna, peran & grup	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
Domain kustom	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
Branding & tema	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
Ekstensi	list_extensions, list_cluster_extensions	install_extension, upgrade_extension, update_extension, uninstall_extension, delete_extension
SMTP	get_smtp	upsert_smtp, delete_smtp, test_smtp
Ekspor & log	list_exports, get_export, get_logs, get_security_logs, query_events	create_export, delete_export, export_cluster_events
Impor & ekspor realm	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
Webhook	list_webhook_event_types, list_webhook_subscriptions, get_webhook_subscription	create_webhook_subscription, update_webhook_subscription, delete_webhook_subscription, test_webhook_subscription

Konvensi: alat destruktif (delete_*, uninstall_extension, cancel_cluster_upgrade, update_theme_content, update_theme_settings, restart_cluster_instances) memerlukan confirm=true. update_theme_settings mengaktifkan atau menonaktifkan exact_theme_names untuk workspace; kunci API pemanggil harus dibuat untuk pemilik atau admin workspace, jika tidak maka akan mendapat 403 bahkan dengan themes:write. Mengaktifkannya memindahkan tema yang ada ke nama layanan persisnya di latar belakang; tema yang kontennya diganti dengan nama persisnya melaporkan restart_required: true dari get_theme/list_themes/update_theme_content hingga restart_cluster_instances menggulirkan instans Keycloak klaster tersebut. Restart dapat ditunda ke jendela pemeliharaan klaster alih-alih diterapkan segera, dilaporkan sebagai deferred: true dan, jika diketahui, next_window. create_cluster bersifat asinkron: polling get_cluster hingga klaster berstatus available. create_domain mengembalikan catatan DNS yang harus dibuat pelanggan; verify_domain memicu pemeriksaan DNS. set_theme_assignment mengaktifkan tema kustom per jenis tema Keycloak (string kosong mengatur ulang ke default bawaan). update_theme_content mengganti arsip tema di tempatnya (ZIP base64 atau JAR Keycloakify di content_base64), mempertahankan ID, nama, dan penetapan realm serta aplikasi tema, sehingga mengedit tema tidak lagi berarti menghapus dan mengunggah ulang; ini memerlukan confirm=true karena arsip yang ditimpa tidak dapat dipulihkan, dan update_theme tetap hanya mengubah nama, deskripsi, dan versi. Lihat docs/theme-content-update.md untuk cara panggilan tersebut dilakukan. update_cluster_security membiarkan pengaturan CAPTCHA tidak tersentuh. Impor/ekspor realm memindahkan konfigurasi satu realm dan terpisah dari create_export, yang membuang seluruh basis data klaster: keduanya asinkron, dan arsip realm selalu dienkripsi, sehingga kata sandi yang digunakan untuk mengekspornya diperlukan untuk mengimpornya lagi. Sebuah realm dapat diimpor langsung dari ekspor yang ada (source_export_id) atau dari arsip yang diunggah (create_realm_import_upload_url, PUT, lalu upload_s3_key); impor membuat realm dan menolak benturan nama alih-alih menimpa, serta memerlukan confirm=true karena membawa pengguna dan kredensial bersamanya.

Prompt

Delapan prompt memberi Anda titik awal ke permukaan alat tersebut. Klien menampilkannya sebagai perintah garis miring atau tindakan yang disarankan; masing-masing menerima argumen (realm, klaster, jendela waktu) dan memandu model melalui alat yang tepat dalam urutan yang tepat.

Prompt	Fungsinya
audit_self_registration	Temukan setiap realm yang masih mengizinkan pendaftaran mandiri, di satu klaster atau semuanya
review_upgrades	Temukan klaster yang tertinggal pada versi Keycloak dan susun jalur pembaruannya
triage_failed_logins	Ambil login gagal terbaru untuk sebuah realm dan kelompokkan berdasarkan IP sumber
review_identity_providers	Daftar koneksi SSO sebuah realm dan periksa apakah koneksi tertentu diaktifkan
review_admin_changes	Tampilkan siapa yang mengubah apa di sebuah realm baru-baru ini, fokus pada pengaturan login dan keamanan
provision_environment	Buat klaster, tambahkan realm, dan sambungkan penyedia identitas, konfirmasi setiap langkah
set_up_custom_domain	Tambahkan domain kustom, serahkan catatan DNS yang tepat, verifikasi, dan arahkan ke sebuah realm
rotate_client_secret	Buat ulang rahasia klien aplikasi dengan dampak ledakan dijelaskan terlebih dahulu

Prompt dibatasi dengan cara yang sama seperti alat yang dirujuknya: tiga yang mengubah hanya ditawarkan ke sesi yang dapat memanggil alat tulis yang dirujuknya, dan instruksinya memberi tahu model untuk mengonfirmasi dengan Anda sebelum mengubah apa pun. Persyaratan confirm=true pada alat destruktif tetap berlaku di atasnya.

Keterampilan

Jika prompt adalah titik awal, keterampilan adalah buku pedoman operasional lengkap yang dimuat model sesuai permintaan. Server mengirimkan empat, disajikan melalui ekstensi SEP-2640 Skills draf: server mendeklarasikan io.modelcontextprotocol/skills dalam kemampuannya, menjawab skills/list dan skills/get, dan menyajikan setiap SKILL.md sebagai sumber daya biasa di skill://<name>/SKILL.md dengan digest sha256 di entri daftarnya. Direktori plugin OpenAI mengimpor keterampilan dalam bentuk persis seperti ini.

Keterampilan	Apa yang dikodekannya
auth-incident-triage	Triase "pengguna tidak dapat masuk": pisahkan gangguan platform dari serangan dan dari perubahan konfigurasi, menggunakan peristiwa, log WAF, dan kesehatan klaster. Hanya-baca
enterprise-sso-rollout	Hubungkan IdP perusahaan ke realm dari awal hingga akhir: validasi penerbit, pendaftaran aplikasi upstream, konfigurasi broker, pengujian koneksi, dan verifikasi terhadap peristiwa masuk nyata
keycloak-migration-doctor	Pra-periksa ekspor, impor, atau migrasi Keycloak terhadap penghambat yang sebenarnya dilihat dukungan (kebijakan skrip, jalur /auth lama, ekspektasi ekspor parsial), dan diagnosis pekerjaan yang gagal dengan membaca error_message nyata alih-alih pemberitahuan dasbor generik
keycloak-upgrade-readiness	Nilai penyimpangan versi, cari tahu apa yang dirusak oleh versi Keycloak baru (ekstensi, tema), dan urutkan peluncuran di seluruh lingkungan dengan ekspor sebagai rencana rollback

Keterampilan mengikuti gerbang yang sama dengan alat yang mereka namai: tiga alur kerja yang dibangun di sekitar alat tulis ditahan dari sesi hanya-baca, dan sesi terbatas hanya ditawari keterampilan yang alatnya benar-benar dimilikinya. Sumbernya ada di internal/tools/skills/, satu direktori per keterampilan, dalam format Agent Skills standar, sehingga juga berfungsi jika disalin langsung ke direktori keterampilan lokal.

Menghubungkan

Untuk HTTP yang dihosting, rute paling sederhana adalah OAuth, yang tidak memerlukan kredensial sama sekali:

claude mcp add --transport http skycloak https://mcp.skycloak.io

Panggilan pertama membuka browser Anda, Anda menyetujui di halaman masuk Skycloak, dan alat muncul. Jika Anda termasuk lebih dari satu ruang kerja, sebutkan yang Anda inginkan:

claude mcp add --transport http skycloak "https://mcp.skycloak.io?workspace=<workspace-id>"

Jika tidak, buat kunci API di dasbor Skycloak dan konfigurasikan klien MCP Anda untuk mengirimkannya sebagai token pembawa:

claude mcp add --transport http skycloak https://mcp.skycloak.io --header "Authorization: Bearer sk_sc_XXX"

Ini menambahkan berikut ini ke .claude.json:

{
  "mcpServers": {
    "skycloak": {
      "type": "http",
      "url": "https://mcp.skycloak.io",
      "headers": {
        "Authorization": "Bearer sk_sc_XXX"
      }
    }
  }
}

Untuk stdio lokal, masuk sekali, lalu arahkan klien Anda ke skycloak-mcp run:

skycloak-mcp init        # one-time browser sign-in; stores a key in your keychain

Claude Desktop / Cursor (lokal, stdio):

{
  "mcpServers": {
    "skycloak": {
      "command": "skycloak-mcp",
      "args": ["run", "--transport", "stdio"]
    }
  }
}

Claude Code:

claude mcp add skycloak -- skycloak-mcp run --transport stdio

Untuk headless / CI (tanpa browser), lewati init dan berikan kunci sebagai gantinya: tambahkan "env": { "SKYCLOAK_API_KEY": "sk_sc_..." } ke konfigurasi, atau claude mcp add skycloak --env SKYCLOAK_API_KEY=sk_sc_... -- skycloak-mcp run --transport stdio.

Tambahkan --allow-writes hanya jika Anda bermaksud membuat perubahan (masuk dengan skycloak-mcp init --allow-writes, atau gunakan kunci dengan cakupan tulis).

Tambahkan ?readonly=true ke URL HTTP yang dihosting untuk mengekspos hanya alat baca-saja untuk sesi HTTP tersebut, atau ?readonly=false untuk meminta permukaan alat yang dapat menulis. Parameter kueri default ke false, tetapi alat tulis hanya didaftarkan saat server dimulai dengan --allow-writes.

Tambahkan ?workspace=<uuid> untuk memilih ruang kerja mana yang akan digunakan sesi OAuth. Ini hanya diperlukan jika Anda termasuk lebih dari satu; dengan satu ruang kerja, server memilihnya untuk Anda, dan jika Anda termasuk beberapa dan tidak menyebutkan satu pun, koneksi gagal dengan pesan yang mencantumkannya.

Menjalankan transport HTTP

skycloak-mcp run --transport http --http-addr :8080

Ini tidak memerlukan kredensial sendiri: pemanggil memberikan kredensial mereka per permintaan, jadi tidak ada yang disuntikkan saat penerapan. GET /healthz dan GET /readyz tidak diautentikasi dan hanya melaporkan bahwa proses berjalan; mereka sengaja tidak memeriksa API Skycloak, sehingga gangguan upstream tidak dapat menggagalkan pemeriksaan semua replika sekaligus. Server tidak menyimpan status sesi, sehingga replika tidak memerlukan afinitas sesi dan dapat diskalakan atau di-roll dengan bebas. SIGTERM menghentikan koneksi baru dan menguras panggilan yang sedang berlangsung.

Jalur OAuth aktif setiap kali SKYCLOAK_ISSUER dan SKYCLOAK_DASHBOARD_URL diatur, yang secara default diatur. GET /.well-known/oauth-protected-resource kemudian dilayani tanpa autentikasi, menamai realm sebagai server otorisasi. Nilai resource diambil dari SKYCLOAK_PUBLIC_URL saat diatur, dan sebaliknya dari Host dan skema permintaan itu sendiri, sehingga penerapan satu host di belakang ingress tidak memerlukan konfigurasi tambahan. Skema berasal dari X-Forwarded-Proto saat ada, dan sebaliknya default ke https untuk apa pun selain host loopback, karena TLS berakhir di upstream dan menerbitkan pengidentifikasi http:// tidak akan cocok dengan URL yang terhubung oleh klien. Setel SKYCLOAK_PUBLIC_URL jika ingress Anda menulis ulang Host. Dokumen juga mencantumkan openid profile email sebagai scopes_supported, dan tantangan WWW-Authenticate mengulanginya sebagai parameter scope, sehingga klien yang membaca salah satunya meminta realm untuk itu: openid diperlukan, karena pertukaran token membuat dasbor memanggil titik akhir userinfo Keycloak dan Keycloak menolak token yang diberikan tanpanya. Token yang tiba tanpanya ditolak saat verifikasi dengan 401 dan tantangan, daripada dibawa ke pertukaran yang tidak dapat berhasil, sehingga klien yang masih memegang hibah dari sebelumnya berhenti mencoba lagi dan masuk lagi. Mengosongkan salah satu variabel penerbit atau dasbor mematikan OAuth sepenuhnya, dan server kembali menantang kunci API dan tidak ada yang lain.

OPENAI_APPS_CHALLENGE_TOKEN menyajikan token verifikasi domain direktori plugin OpenAI di /.well-known/openai-apps-challenge, sebagai teks biasa dan tidak ada yang lain. Jika tidak diatur, rute tidak terdaftar dan jalur 404.

Log startup satu baris dengan kabel yang diselesaikannya (oauth=, issuer=, dashboard=, public_url=, endpoint=, allow_writes=), sehingga penerapan yang salah konfigurasi dapat terlihat tanpa penerapan ulang. Setiap permintaan yang ditolak di jalur OAuth mencatat satu baris yang menamai tahap yang gagal (verify, exchange atau scopes), status yang diterima pemanggil, dan kesalahan yang mendasarinya. Kegagalan verifikasi menambahkan pemeriksaan yang menolak token (expired, wrong_issuer, bad_signature, unknown_key_id, wrong_token_type, no_openid_scope, dan seterusnya); kegagalan pertukaran menambahkan status dasbor dan host yang dipanggil. Pemanggil muncul sebagai subjek token setelah diverifikasi, dan tidak pernah sebagai kredensial: token akses, header Authorization, dan kunci API yang dibuat tidak pernah dicatat.

Konfigurasi

Variabel env	Default
SKYCLOAK_API_KEY	tidak ada (opsional untuk stdio; klien HTTP menyediakan header API-Key sebagai gantinya)
SKYCLOAK_ENDPOINT	https://api.skycloak.io
SKYCLOAK_API_VERSION	versi API saat ini
SKYCLOAK_ISSUER	https://login.app.skycloak.io/realms/skycloak (masuk CLI, dan server otorisasi yang digunakan transport HTTP untuk memverifikasi token)
SKYCLOAK_CLIENT_ID	skycloak-mcp (alur perangkat CLI saja)
SKYCLOAK_DASHBOARD_URL	https://app.skycloak.io (membuat kunci CLI dan kunci sesi HTTP)
SKYCLOAK_PUBLIC_URL	tidak ada (diturunkan dari setiap permintaan; atur saat ingress menulis ulang Host)
OPENAI_APPS_CHALLENGE_TOKEN	Menyajikan token verifikasi direktori plugin OpenAI di /.well-known/openai-apps-challenge. Jika tidak diatur, jalur itu 404.

Perintah: init (masuk browser), run (melayani), logout (hapus kunci tersimpan). init menerima --workspace <id>, --allow-writes, --allow-credentials, dan --ttl-days (default 90).

Bendera	Default	Deskripsi
--transport	stdio	stdio atau http
--http-addr	:8080	alamat listen untuk transport HTTP
--allow-writes	false	aktifkan alat mutasi untuk stdio dan izinkan sesi HTTP dengan readonly=false untuk mendaftarkan alat tulis

Pengembangan

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

Klien API di bawah internal/apiclient dihasilkan dari spesifikasi OpenAPI Skycloak dengan oapi-codegen.

Menjaga sinkronisasi dengan API

Klien di internal/apiclient dihasilkan dari internal/apiclient/openapi.yaml dengan oapi-codegen; jalankan make generate untuk menyegarkannya. CI gagal jika kode yang dihasilkan yang dikomit menyimpang dari spesifikasi. Permintaan dicoba ulang pada 429/5xx dengan backoff yang sadar Retry-After.

Distribusi

Dirilis sebagai biner GitHub dan gambar kontainer ghcr.io/sky-cloak/skycloak-mcp pada setiap tag, dan diterbitkan ke MCP Registry sebagai io.skycloak/skycloak-mcp. Kebanyakan orang tidak membutuhkan keduanya: server yang dihosting tidak memerlukan instalasi.

Keamanan

Harap laporkan kerentanan secara pribadi. Lihat SECURITY.md.

Kontributor

Dibangun di Skycloak oleh Guilliano Molaire, Neville Omangi, dan Aphilas. Riwayat repositori di-squash saat dibuka, sehingga log commit tidak mencerminkan siapa menulis apa.

Lisensi

Apache-2.0. Deskripsi OpenAPI di internal/apiclient/openapi.yaml dihasilkan dari API platform Skycloak dan (c) Skycloak; disertakan di sini agar klien dapat dihasilkan dan diverifikasi. Lihat NOTICE.