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 client ID, tanpa konfigurasi. Browser Anda terbuka, Anda masuk ke Skycloak, dan alat-alat pun 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 ter-hosting, 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 diterima ditukar dengan kunci API berumur pendek yang tercakup dalam workspace tempat sesi berjalan. Kunci berlaku selama satu jam dan diperbarui otomatis. Tidak ada yang disimpan dalam konfigurasi klien Anda.
• HTTP ter-hosting, 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 peran Anda. Melalui OAuth, daftar alat dipangkas sesuai 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 ter-hosting 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 paket Skycloak Anda; pada respons 429, server menampilkan Retry-After.

Alat

129 alat: 58 hanya-baca dan 71 tulis. Alat hanya-baca selalu tersedia. Di server ter-hosting, 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, set_cluster_maintenance_window, delete_cluster_maintenance_window
Keamanan edge	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	set_theme_assignment, set_client_theme_assignment, update_theme, 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) memerlukan confirm=true. 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_cluster_security tidak menyentuh pengaturan CAPTCHA. 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	Daftarkan koneksi SSO sebuah realm dan periksa apakah koneksi tertentu diaktifkan
review_admin_changes	Tampilkan siapa yang mengubah apa di sebuah realm baru-baru ini, dengan fokus pada pengaturan login dan keamanan
provision_environment	Buat klaster, tambahkan realm, dan sambungkan penyedia identitas, dengan konfirmasi di 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 sebuah aplikasi dengan dampak ledakan dijelaskan terlebih dahulu

Prompt dibatasi dengan cara yang sama seperti alat yang disebutnya: 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 menyertakan empat keterampilan, disajikan melalui ekstensi draf SEP-2640 Skills: 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 ringkasan 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	Sambungkan IdP perusahaan ke sebuah realm dari ujung ke ujung: validasi penerbit, pendaftaran aplikasi hulu, konfigurasi broker, pengujian koneksi, dan verifikasi terhadap peristiwa login nyata
keycloak-migration-doctor	Pra-periksa ekspor, impor, atau migrasi Keycloak terhadap penghambat yang benar-benar dilihat dukungan (kebijakan skrip, jalur /auth lama, ekspektasi ekspor parsial), dan diagnosis pekerjaan yang gagal dengan membaca error_message aslinya alih-alih pemberitahuan dasbor umum
keycloak-upgrade-readiness	Nilai penyimpangan versi, tentukan apa yang dirusak versi Keycloak baru (ekstensi, tema), dan urutkan peluncuran di seluruh lingkungan dengan ekspor sebagai rencana pemulihan

Keterampilan mengikuti pembatasan yang sama seperti alat yang disebutnya: tiga alur kerja yang dibangun di sekitar alat tulis ditahan dari sesi hanya-baca, dan sesi dengan cakupan 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 ter-hosting, 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-alat pun muncul. Jika Anda termasuk lebih dari satu workspace, 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 hal berikut 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 berniat melakukan perubahan (masuk dengan skycloak-mcp init --allow-writes, atau gunakan kunci dengan lingkup tulis).

Tambahkan ?readonly=true ke URL HTTP yang di-hosting untuk hanya mengekspos alat baca-saja untuk sesi HTTP tersebut, atau ?readonly=false untuk meminta permukaan alat yang mendukung tulis. Parameter kueri defaultnya adalah false, tetapi alat tulis hanya didaftarkan ketika server dimulai dengan --allow-writes.

Tambahkan ?workspace=<uuid> untuk memilih workspace mana yang digunakan oleh sesi OAuth. Ini hanya diperlukan jika Anda tergabung dalam lebih dari satu workspace; dengan satu workspace, server akan memilihkannya untuk Anda, dan jika Anda tergabung dalam beberapa workspace dan tidak menyebutkan satupun, koneksi akan 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 deployment. GET /healthz dan GET /readyz tidak diautentikasi dan hanya melaporkan bahwa proses berjalan; keduanya sengaja tidak memeriksa API Skycloak, sehingga gangguan hulu tidak dapat menggagalkan probe 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 memang diatur secara default. GET /.well-known/oauth-protected-resource kemudian dilayani tanpa autentikasi, menyebut realm sebagai server otorisasi. Nilai resource-nya diambil dari SKYCLOAK_PUBLIC_URL jika diatur, dan selain itu dari Host dan skema permintaan itu sendiri, sehingga deployment satu-host di belakang ingress tidak memerlukan konfigurasi tambahan. Skema berasal dari X-Forwarded-Proto jika ada, dan selain itu default ke https untuk apa pun kecuali host loopback, karena TLS berakhir di hulu dan menerbitkan pengidentifikasi http:// tidak akan cocok dengan URL yang digunakan klien untuk terhubung. Atur SKYCLOAK_PUBLIC_URL jika ingress Anda menulis ulang Host. Dokumen ini juga mencantumkan openid profile email sebagai scopes_supported-nya, dan tantangan WWW-Authenticate mengulanginya sebagai parameter scope, sehingga klien yang membaca salah satunya akan memintanya ke realm: openid wajib, karena pertukaran token membuat dasbor memanggil endpoint 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 grant dari sebelumnya berhenti mencoba lagi dan masuk kembali. Mengosongkan salah satu variabel issuer atau dasbor akan mematikan OAuth sepenuhnya, dan server kembali meminta 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 tersebut mengembalikan 404.

Log startup menampilkan satu baris dengan wiring yang diselesaikannya (oauth=, issuer=, dashboard=, public_url=, endpoint=, allow_writes=), sehingga deployment yang salah konfigurasi dapat terdeteksi tanpa redeploy. Setiap permintaan yang ditolak di jalur OAuth mencatat satu baris yang menyebutkan 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 (hanya alur perangkat CLI)
SKYCLOAK_DASHBOARD_URL	https://app.skycloak.io (membuat kunci CLI dan kunci sesi HTTP)
SKYCLOAK_PUBLIC_URL	tidak ada (diturunkan dari setiap permintaan; atur jika ingress menulis ulang Host)
OPENAI_APPS_CHALLENGE_TOKEN	Menyajikan token verifikasi direktori plugin OpenAI di /.well-known/openai-apps-challenge. Jika tidak diatur, jalur tersebut mengembalikan 404.

Perintah: init (masuk melalui browser), run (melayani), logout (menghapus kunci yang 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	mengaktifkan alat mutasi untuk stdio dan mengizinkan 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 dibuat dari spesifikasi OpenAPI Skycloak dengan oapi-codegen.

Menjaga sinkronisasi dengan API

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

Distribusi

Dirilis sebagai biner GitHub dan image kontainer ghcr.io/sky-cloak/skycloak-mcp pada setiap tag, dan dipublikasikan ke MCP Registry sebagai io.skycloak/skycloak-mcp. Kebanyakan orang tidak memerlukan keduanya: server yang di-hosting 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 dibuat dari API platform Skycloak dan merupakan (c) Skycloak; disertakan di sini agar klien dapat dibuat dan diverifikasi. Lihat NOTICE.