Skycloak
offiziellMCP-Server für Skycloak-verwaltetes Keycloak. Verwalten Sie Cluster, Realms, Anwendungen, SSO und Benutzer über jeden MCP-Client.
Was kann man mit Skycloak MCP machen?
- Clusterinventar und Upgrade-Status — Liste deine Keycloak-Cluster auf, prüfe, bei welchen Upgrades ausstehen, und ermittle den Upgrade-Pfad für jeden Cluster.
- Realm- und Anwendungsverwaltung — Erstelle oder aktualisiere Realms und Anwendungen, verwalte Anwendungsrollen und rotiere Client-Secrets.
- Einrichtung von Identity Providern — Füge einem Realm OIDC-Identity-Provider hinzu, teste die Verbindung und überprüfe bestehende SSO-Verbindungen.
- Überprüfung von Benutzern und Zugriffsrechten — Liste Realm-Benutzer, Rollen und Gruppen auf und frage Ereignisse ab, um zu sehen, wer hinzugefügt wurde oder was sich kürzlich geändert hat.
- SIEM- und Webhook-Ziele — Erstelle und teste SIEM-Ziele oder Webhook-Abonnements, die Admin-Ereignisse an einen externen Endpunkt weiterleiten.
- Geführte Workflows — Führe Prompts wie
review_upgradesodertriage_failed_loginsaus, die dich Schritt für Schritt durch die passenden Tools führen.
Dokumentation
skycloak-mcp
Offizieller Server für das Model Context Protocol für Skycloak (verwaltetes Keycloak): Verwalten Sie Ihre Cluster, Realms, Anwendungen und SSO über jeden MCP-Client (Claude Desktop, Claude Code, Cursor).
Status: frühe Version. Die Tool-Abdeckung wächst; im Änderungsprotokoll erfahren Sie, was verfügbar ist.
Schnellstart
claude mcp add --transport http skycloak https://mcp.skycloak.io
Kein API-Schlüssel, keine Client-ID, keine Konfiguration. Ihr Browser wird geöffnet, Sie melden sich bei Skycloak an und die Tools werden angezeigt. Jeder MCP-Client, der streamable HTTP unterstützt, funktioniert genauso: Geben Sie ihm die URL und sonst nichts.
Fragen Sie anschließend nach etwas:
- „Welche meiner Keycloak-Cluster haben veraltete Upgrades?“
- „Erstelle ein Staging-Realm im EU-Cluster mit Google- und GitHub-Anmeldung.“
- „Wer wurde in der letzten Woche zum Produktions-Realm hinzugefügt?“
- „Richte ein SIEM-Ziel ein, das Admin-Ereignisse an unseren Datadog-Webhook weiterleitet.“
Authentifizierung und Sicherheit
- Gehostetes HTTP mit OAuth (keine Zugangsdaten zu konfigurieren). Richten Sie Ihren Client ohne Header auf
https://mcp.skycloak.ioaus. Der Server antwortet mit401und einem Verweis auf seine RFC 9728-Metadaten unter/.well-known/oauth-protected-resource. Der Client führt den Browser-Autorisierungscode-Ablauf über das Skycloak-Anmelde-Realm aus. Das erhaltene Zugriffstoken wird gegen einen kurzlebigen, auf den Workspace beschränkten API-Schlüssel ausgetauscht, mit dem die Sitzung ausgeführt wird. Der Schlüssel ist eine Stunde gültig und wird automatisch erneuert. In Ihrer Client-Konfiguration wird nichts gespeichert. - Gehostetes HTTP mit einem API-Schlüssel. Erstellen Sie einen Schlüssel im Skycloak-Dashboard und senden Sie ihn als
Authorization: Bearer <key>(oderAPI-Key: <key>). Jede Anfrage enthält ihre eigenen Zugangsdaten und handelt ausschließlich im Workspace dieser Zugangsdaten. Der Server speichert keinen Sitzungsstatus, daher übernimmt eine Anfrage niemals den Status eines anderen Aufrufers. Schlüssel werden vor der Verwendung nicht überprüft: Die Skycloak-API ist maßgeblich, daher wird ein ungültiger Schlüssel beim ersten Tool-Aufruf als401angezeigt und nicht bereits beim Verbindungsaufbau. - Tools richten sich nach Ihrer Rolle. Bei OAuth wird die Tool-Liste auf die Tools beschränkt, die von den Berechtigungsumfängen der Sitzung zugelassen werden. Ein schreibgeschütztes Workspace-Mitglied sieht daher keine Schreib-Tools, die mit
403antworten würden. Bei einem API-Schlüssel wird die gesamte Oberfläche registriert, da der Server die Berechtigungsumfänge eines Schlüssels nicht einsehen kann. Ein nicht autorisierter Aufruf wird von der API als403gemeldet. - Lokales stdio. Führen Sie
skycloak-mcp initaus und bestätigen Sie im Browser (OAuth-2.0-Geräteautorisierungsablauf). Dabei wird ein auf den Workspace beschränkter API-Schlüssel erstellt, im Schlüsselbund Ihres Betriebssystems gespeichert und Ihr Standard-Workspace automatisch erkannt (übergeben Sie--workspace <id>, um einen anderen auszuwählen).skycloak-mcp logoutentfernt den gespeicherten Schlüssel. - Headless / CI. Legen Sie die Umgebungsvariable
SKYCLOAK_API_KEYfest (erstellen Sie einen Schlüssel im Skycloak-Dashboard), um den Browser vollständig zu umgehen. Diese Variable hat immer Vorrang vor dem Schlüsselbund. Wenn kein Schlüssel vorhanden und kein Schlüsselbund erreichbar ist – etwa in einem Container oder auf einem Host ohne Secret Service –, startet der stdio-Server trotzdem und listet seine Tools auf, sodass ein Verzeichnis ihn untersuchen kann. Jeder Aufruf schlägt dann mit einem Fehler fehl, der beide Möglichkeiten zur Bereitstellung von Zugangsdaten nennt. - Schreibzugriffe werden durch Ihre Zugangsdaten gesteuert, nicht durch ein Flag. Der gehostete Server unter
https://mcp.skycloak.iounterstützt Schreibzugriffe. Was Sie tatsächlich ändern können, hängt von den Berechtigungsumfängen Ihres Schlüssels und Ihrer Workspace-Rolle ab: Ein schreibgeschütztes Mitglied kann nichts ändern, unabhängig davon, was die Tool-Liste anzeigt. Fügen Sie der URL?readonly=truehinzu, um für eine Sitzung eine schreibgeschützte Tool-Oberfläche zu erzwingen. Beim lokalen Binary ist es umgekehrt: Es registriert keine Schreib-Tools, sofern es nicht mit--allow-writesgestartet wird. - Cluster-Zugangsdaten sind optional.
get_cluster_credentialsgibt die Keycloak-Admin-Zugangsdaten eines Clusters zurück, die ein Assistent mit dem Schlüssel dann sehen würde. Daher fordertinitdiesen Berechtigungsumfang standardmäßig nicht an. Verwenden Sie einen Schlüssel, der diesen Umfang enthält: Erstellen Sie einen im Dashboard oder melden Sie sich über stdio mitskycloak-mcp init --allow-credentialsan. Ohne diesen Umfang gibt das Tool einen 403-Fehler zurück, der beide Möglichkeiten erläutert. - Destruktive Tools erfordern eine Bestätigung: Zum Beispiel muss beim Löschen eines Realms das Argument
confirm=trueausdrücklich angegeben werden. - Anfragen werden gemäß Ihrem Skycloak-Tarif begrenzt; bei einer
429-Antwort gibt der ServerRetry-Afteraus.
Tools
143 Tools: 63 schreibgeschützte und 80 schreibende. Schreibgeschützte Tools sind immer verfügbar. Auf dem gehosteten Server werden auch die Schreib-Tools registriert und durch die Berechtigungsumfänge Ihrer Zugangsdaten eingeschränkt. Das lokale Binary registriert sie nur, wenn es mit --allow-writes gestartet wird.
Tool-Namen haben das Präfix skycloak_, das in der folgenden Tabelle weggelassen wird. Daher entspricht list_clusters in Ihrem Client skycloak_list_clusters.
| Bereich | Schreibgeschützt | Schreiben (--allow-writes) |
|---|---|---|
| Cluster | 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 |
| Edge-Sicherheit | get_cluster_security, list_cluster_captcha_domains | update_cluster_security, add_cluster_captcha_domain, remove_cluster_captcha_domain |
| Private Link | get_cluster_private_link | update_cluster_private_link |
| Realms | list_realms, get_realm | create_realm, update_realm, delete_realm |
| Anwendungen | list_applications, get_application, list_application_roles, get_application_role, list_application_sessions | create_application, update_application, delete_application, create_application_role, update_application_role, delete_application_role, assign_application_role, remove_application_role, rotate_application_secret |
| Identitätsanbieter | 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 |
| Benutzer, Rollen und Gruppen | 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 |
| Benutzerdefinierte Domains | 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 und Themes | 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 |
| Erweiterungen | list_extensions, list_cluster_extensions | install_extension, upgrade_extension, update_extension, uninstall_extension, delete_extension |
| SMTP | get_smtp | upsert_smtp, delete_smtp, test_smtp |
| Exporte und Protokolle | list_exports, get_export, get_logs, get_security_logs, query_events | create_export, delete_export, export_cluster_events |
| Realm-Import und -Export | 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 |
| Webhooks | 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 |
Konventionen: Destruktive Tools (delete_*, uninstall_extension, cancel_cluster_upgrade, update_theme_content, update_theme_settings, restart_cluster_instances) erfordern confirm=true. update_theme_settings aktiviert oder deaktiviert exact_theme_names für den Workspace. Der API-Schlüssel des Aufrufers muss für einen Workspace-Eigentümer oder -Administrator erstellt worden sein, andernfalls wird selbst mit themes:write der Fehler 403 ausgegeben. Beim Aktivieren werden vorhandene Themes im Hintergrund auf ihre exakt ausgelieferten Namen umgestellt. Für ein Theme, dessen Inhalt unter seinem exakten Namen ersetzt wurde, wird von get_theme/list_themes/update_theme_content bis zum Neustart der Keycloak-Instanzen des Clusters durch restart_cluster_instances der Status restart_required: true gemeldet. Ein Neustart kann bis zum Wartungsfenster des Clusters aufgeschoben werden, statt sofort zu erfolgen; dies wird als deferred: true und, sofern bekannt, als next_window gemeldet. create_cluster läuft asynchron: Rufen Sie get_cluster wiederholt auf, bis der Cluster den Status available hat. create_domain gibt die DNS-Einträge zurück, die der Kunde erstellen muss; verify_domain löst eine DNS-Prüfung aus. set_theme_assignment aktiviert ein benutzerdefiniertes Theme für jeden Keycloak-Theme-Typ (eine leere Zeichenfolge setzt den integrierten Standard zurück). update_theme_content ersetzt das Archiv eines Themes direkt (Base64-ZIP oder Keycloakify-JAR in content_base64) und behält dabei die ID, den Namen, das Realm sowie die Anwendungszuweisungen des Themes bei. Ein Theme zu bearbeiten bedeutet damit nicht mehr, es zu löschen und erneut hochzuladen. Dafür ist confirm=true erforderlich, da das überschriebene Archiv nicht wiederhergestellt werden kann. update_theme ändert weiterhin nur den Namen, die Beschreibung und die Version. Unter docs/theme-content-update.md erfahren Sie, wie dieser Aufruf erfolgt. update_cluster_security lässt CAPTCHA-Einstellungen unverändert. get_realm gibt den frontend_url des Realms zurück, sofern einer festgelegt ist. update_realm legt ihn fest oder löscht ihn bei Angabe einer leeren Zeichenfolge, während die übrigen Einstellungen des Realms unverändert bleiben. Eine Änderung wirkt sich auf den Issuer, die Links und den Passkey-Ursprung des Realms aus. Die API verweigert den Aufruf mit 403 für einen nicht dedizierten Cluster, mit 422 für das Realm master oder eine ungültige URL und mit 409 für ein Realm, das über eine benutzerdefinierte Domain bereitgestellt wird. Das Tool gibt die Ablehnung unverändert zurück. update_cluster_private_link legt die Azure-Abonnement-IDs fest, die eine Verbindung mit dem Private Link eines Clusters herstellen dürfen, und gibt den neuen Status zurück: Die Liste ersetzt die gespeicherte Liste, eine leere Liste löscht sie, und wenn sie oder enabled weggelassen wird, bleibt dieser Teil unverändert. Die API verweigert den Aufruf mit 403, wenn der Tarif kein privates Netzwerk umfasst, mit 422, wenn für den Standort des Clusters kein Azure Private Link verfügbar ist oder eine ID keine gültige GUID ist, und mit 409, wenn Private Link deaktiviert wird, während der öffentliche Zugriff deaktiviert ist. Das Tool gibt die Ablehnung unverändert zurück. Der Realm-Import und -Export verschiebt die Konfiguration eines einzelnen Realms und ist von create_export getrennt, das die Datenbank eines gesamten Clusters exportiert. Beide Vorgänge laufen asynchron ab. Das Realm-Archiv ist immer verschlüsselt, daher wird zum erneuten Import das beim Export verwendete Passwort benötigt. Ein Realm kann direkt aus einem vorhandenen Export (source_export_id) oder aus einem hochgeladenen Archiv (create_realm_import_upload_url, PUT, dann upload_s3_key) importiert werden. Beim Import wird ein Realm erstellt. Bei einem Namenskonflikt wird der Vorgang abgelehnt, statt ein vorhandenes Realm zu überschreiben. Dafür ist confirm=true erforderlich, da dabei Benutzer und Zugangsdaten übernommen werden.
OpenFGA-Instanzen: Jedes OpenFGA-Tool benötigt cluster_id. create_openfga_instance bindet eine OpenFGA-Instanz an genau ein realm des Clusters; ein Realm kann höchstens eine Instanz haben. Das Tool gibt 403 zurück, wenn der Tarif des Workspace OpenFGA nicht umfasst oder der Workspace sein Instanzlimit erreicht hat, 409, wenn das Realm bereits eine Instanz hat, und 422, wenn das Realm master ist, nicht existiert oder deaktiviert ist. Der Vorgang läuft asynchron ab: Rufen Sie get_openfga_instance wiederholt auf, bis status den Status ready oder failed hat. Die Instanz akzeptiert nur Token aus diesem Realm, die ihre Audience enthalten. get_openfga_instance gibt api_url, issuer und audience zurück, die für den Aufruf benötigt werden. Der Audience-Mapper, der die Audience in die Token des Realms einfügt, wird in Keycloak hinzugefügt. Auflisten und Löschen funktionieren auch ohne OpenFGA-Zugriff. delete_openfga_instance entfernt die Bereitstellung, die Route und die Datenbank. Die darin enthaltenen Autorisierungsdaten können nicht wiederhergestellt werden. Die Instanz zeigt den Status deleting, bis sie entfernt wurde.
Cluster-Standorte: location auf create_cluster und in dem, was list_clusters, get_cluster und list_cluster_locations zurückgeben, ist in jedem Fall einer von us (US East), us-west (US West), ca (Kanada), eu (Europa) oder au (Australien). us bedeutet immer US East. us-west ist nur für Workspaces verfügbar, denen Zugriff darauf gewährt wurde: list_cluster_locations listet alle Standorte auf, für die available in deinem Workspace gesetzt ist. Wenn du einen Cluster an einem Standort erstellst, den du nicht verwenden kannst, gibt die API den Fehler 400 „location not available“ zurück.
Prompts
Acht Prompts bieten dir einen Einstieg in diese Tool-Oberfläche. Clients stellen sie als Slash-Befehle oder vorgeschlagene Aktionen bereit. Jeder Prompt nimmt Argumente entgegen (Realm, Cluster, Zeitraum) und führt das Modell in der richtigen Reihenfolge durch die passenden Tools.
| Prompt | Funktion |
|---|---|
audit_self_registration | Alle Realms finden, in denen die Selbstregistrierung noch möglich ist, in einem oder allen Clustern |
review_upgrades | Cluster erkennen, deren Keycloak-Version veraltet ist, und den Upgrade-Pfad aufzeigen |
triage_failed_logins | Kürzlich fehlgeschlagene Anmeldungen für einen Realm abrufen und nach Quell-IP gruppieren |
review_identity_providers | SSO-Verbindungen eines Realms auflisten und prüfen, ob eine bestimmte aktiviert ist |
review_admin_changes | Anzeigen, wer kürzlich was in einem Realm geändert hat, mit Schwerpunkt auf Anmelde- und Sicherheitseinstellungen |
provision_environment | Einen Cluster erstellen, einen Realm hinzufügen und einen Identity Provider einrichten, wobei jeder Schritt bestätigt wird |
set_up_custom_domain | Eine benutzerdefinierte Domain hinzufügen, die genauen DNS-Einträge ausgeben, sie verifizieren und einem Realm zuordnen |
rotate_client_secret | Das Client-Secret einer Anwendung neu generieren und zuvor die Auswirkungen genau darlegen |
Prompts unterliegen denselben Zugriffsbeschränkungen wie die darin genannten Tools: Die drei Prompts, die Änderungen vornehmen, werden nur Sitzungen angeboten, die die referenzierten Schreib-Tools aufrufen können. Ihre Anweisungen fordern das Modell auf, vor Änderungen deine Bestätigung einzuholen. Zusätzlich gilt weiterhin die Anforderung confirm=true für destruktive Tools.
Skills
Während ein Prompt als Einstieg dient, ist ein Skill ein vollständiges operatives Handbuch, das das Modell bei Bedarf lädt. Der Server stellt vier Skills über die Entwurfsversion der SEP-2640 Skills-Erweiterung bereit: Er deklariert io.modelcontextprotocol/skills in seinen Capabilities, beantwortet skills/list und skills/get und stellt jeden SKILL.md als gewöhnliche Ressource unter skill://<name>/SKILL.md bereit, mit einem sha256-Digest im zugehörigen Listeneintrag. OpenAIs Plugin-Verzeichnis importiert Skills genau in diesem Format.
| Skill | Inhalt |
|---|---|
auth-incident-triage | „Benutzer können sich nicht anmelden“ untersuchen: Plattformausfälle von Angriffen und Konfigurationsänderungen unterscheiden, anhand von Ereignissen, WAF-Protokollen und Clusterzustand. Nur lesend |
enterprise-sso-rollout | Einen Enterprise-IdP vollständig in einen Realm integrieren: Issuer-Validierung, Registrierung der Upstream-App, Broker-Konfiguration, Verbindungstest und Überprüfung anhand echter Anmeldeereignisse |
keycloak-migration-doctor | Einen Keycloak-Export, -Import oder eine Migration vorab auf die Hindernisse prüfen, die der Support tatsächlich beobachtet (Skriptrichtlinien, der alte Pfad /auth, Erwartungen an Teil-Exporte), und einen fehlgeschlagenen Job diagnostizieren, indem sein tatsächliches error_message gelesen wird, statt des allgemeinen Dashboard-Hinweises |
keycloak-upgrade-readiness | Versionsabweichungen bewerten, ermitteln, was die neue Keycloak-Version beeinträchtigt (Erweiterungen, Themes), und den Rollout über Umgebungen hinweg mit einem Export als Rollback-Plan staffeln |
Skills unterliegen denselben Zugriffsbeschränkungen wie die darin genannten Tools: Die drei Workflows, die auf Schreib-Tools basieren, sind für Sitzungen mit reinem Lesezugriff nicht verfügbar. Einer Sitzung mit eingeschränktem Zugriff wird nur ein Skill angeboten, dessen Tools sie tatsächlich verwenden kann. Die Quellen liegen in internal/tools/skills/, jeweils in einem Verzeichnis pro Skill und im standardisierten Format Agent Skills. Sie funktionieren daher auch, wenn sie direkt in ein lokales Skills-Verzeichnis kopiert werden.
Verbindung herstellen
Für gehostetes HTTP ist OAuth der einfachste Weg; dafür sind keine Zugangsdaten erforderlich:
claude mcp add --transport http skycloak https://mcp.skycloak.io
Beim ersten Aufruf wird dein Browser geöffnet. Du bestätigst die Anmeldung auf der Skycloak-Anmeldeseite, und die Tools werden verfügbar. Wenn du mehreren Workspaces angehörst, gib den gewünschten an:
claude mcp add --transport http skycloak "https://mcp.skycloak.io?workspace=<workspace-id>"
Alternativ kannst du im Skycloak-Dashboard einen API-Schlüssel erstellen und deinen MCP-Client so konfigurieren, dass er ihn als Bearer-Token sendet:
claude mcp add --transport http skycloak https://mcp.skycloak.io --header "Authorization: Bearer sk_sc_XXX"
Dadurch wird Folgendes zu .claude.json hinzugefügt:
{
"mcpServers": {
"skycloak": {
"type": "http",
"url": "https://mcp.skycloak.io",
"headers": {
"Authorization": "Bearer sk_sc_XXX"
}
}
}
}
Gemini CLI installiert den gehosteten Server als Erweiterung anhand des Manifests in diesem Repository:
gemini extensions install https://github.com/sky-cloak/skycloak-mcp
Antigravity installiert den gehosteten Server als Plugin anhand des Bundles in plugins/skycloak/:
agy plugin install ./plugins/skycloak
Copilot CLI installiert ihn über das Agent-Plugins-Manifest im Stammverzeichnis des Repositorys, sobald der Eintrag genehmigt wurde:
copilot plugin install skycloak@awesome-copilot
Für lokales stdio melde dich einmal an und verweise dann deinen Client auf 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
Für Headless-/CI-Umgebungen (ohne Browser) überspringe init und übergib stattdessen den Schlüssel: Füge "env": { "SKYCLOAK_API_KEY": "sk_sc_..." } zur Konfiguration hinzu oder claude mcp add skycloak --env SKYCLOAK_API_KEY=sk_sc_... -- skycloak-mcp run --transport stdio.
Füge --allow-writes nur hinzu, wenn du Änderungen vornehmen möchtest (Anmeldung mit skycloak-mcp init --allow-writes oder Verwendung eines Schlüssels mit Schreibzugriff).
Füge ?readonly=true zu einer gehosteten HTTP-URL hinzu, um für diese HTTP-Sitzung nur lesende Tools bereitzustellen, oder ?readonly=false, um die Tool-Oberfläche mit Schreibzugriff anzufordern. Der Abfrageparameter ist standardmäßig false, Schreib-Tools werden jedoch nur registriert, wenn der Server mit --allow-writes gestartet wurde.
Füge ?workspace=<uuid> hinzu, um festzulegen, für welchen Workspace eine OAuth-Sitzung ausgeführt wird. Das ist nur erforderlich, wenn du mehreren Workspaces angehörst. Bei einem einzelnen Workspace wählt der Server ihn automatisch aus. Wenn du mehreren angehörst und keinen angibst, schlägt die Verbindung mit einer Meldung fehl, in der diese Workspaces aufgeführt sind.
HTTP-Transport ausführen
skycloak-mcp run --transport http --http-addr :8080
Der Transport benötigt keine eigenen Zugangsdaten: Aufrufer übermitteln ihre Zugangsdaten bei jeder Anfrage, daher wird bei der Bereitstellung nichts injiziert. GET /healthz und GET /readyz sind nicht authentifiziert und melden lediglich, dass der Prozess läuft. Sie prüfen die Skycloak-API absichtlich nicht, damit ein vorübergehender Ausfall des Upstream-Dienstes nicht gleichzeitig die Probe jeder Replik fehlschlagen lässt. Der Server speichert keinen Sitzungszustand, daher benötigen Replikas keine Sitzungsaffinität und können beliebig skaliert oder neu gestartet werden. SIGTERM nimmt keine neuen Verbindungen mehr an und lässt laufende Aufrufe auslaufen.
Der OAuth-Pfad ist aktiv, wenn SKYCLOAK_ISSUER und SKYCLOAK_DASHBOARD_URL gesetzt sind; standardmäßig sind sie das. GET /.well-known/oauth-protected-resource wird dann nicht authentifiziert bereitgestellt und gibt den Realm als Autorisierungsserver an. Sein Wert für resource stammt aus SKYCLOAK_PUBLIC_URL, sofern gesetzt, andernfalls aus Host und dem Schema der jeweiligen Anfrage. Daher ist für eine Bereitstellung auf einem einzelnen Host hinter einem Ingress keine zusätzliche Konfiguration erforderlich. Das Schema stammt aus X-Forwarded-Proto, sofern vorhanden, und ist andernfalls für alle Hosts außer Loopback-Hosts standardmäßig https, da TLS vorgelagert terminiert wird und die Veröffentlichung eines http://-Identifiers nicht mit der URL übereinstimmen würde, über die sich der Client verbunden hat. Setze SKYCLOAK_PUBLIC_URL, wenn dein Ingress Host umschreibt. Das Dokument führt außerdem openid profile email als scopes_supported auf, und die WWW-Authenticate-Challenge wiederholt sie als Parameter scope. Ein Client, der eines der beiden Dokumente liest, fordert den Realm daher dazu auf. openid ist erforderlich, weil beim Token-Austausch das Dashboard den Userinfo-Endpunkt von Keycloak aufruft und Keycloak ein Token ablehnt, das ohne diesen Wert gewährt wurde. Ein Token, bei dem dieser Wert fehlt, wird bei der Verifizierung mit einem 401 und der Challenge abgelehnt, statt an einen Austausch weitergegeben zu werden, der nicht erfolgreich sein kann. So hört ein Client, der noch eine ältere Berechtigung besitzt, auf, es erneut zu versuchen, und meldet sich erneut an. Wird eine der Issuer- oder Dashboard-Variablen geleert, wird OAuth vollständig deaktiviert. Der Server fordert dann wieder ausschließlich einen API-Schlüssel an.
OPENAI_APPS_CHALLENGE_TOKEN stellt das Domain-Verifizierungstoken für OpenAIs Plugin-Verzeichnis unter /.well-known/openai-apps-challenge als reinen Text bereit. Ist die Variable nicht gesetzt, wird die Route nicht registriert und der Pfad liefert 404.
Beim Start wird eine Zeile mit der ermittelten Konfiguration protokolliert (oauth=, issuer=, dashboard=, public_url=, endpoint=, allow_writes=), sodass eine falsch konfigurierte Bereitstellung ohne erneute Bereitstellung erkannt werden kann. Jede Anfrage, die über den OAuth-Pfad abgelehnt wird, erzeugt eine Zeile mit der fehlgeschlagenen Phase (verify, exchange oder scopes), dem Status, den der Aufrufer erhalten hat, und dem zugrunde liegenden Fehler. Bei einem Verifizierungsfehler wird zusätzlich die Prüfung protokolliert, an der das Token gescheitert ist (expired, wrong_issuer, bad_signature, unknown_key_id, wrong_token_type, no_openid_scope usw.). Bei einem Austauschfehler werden der Status des Dashboards und der aufgerufene Host ergänzt. Sobald das Token verifiziert wurde, wird der Aufrufer anhand des Token-Subjekts angegeben, niemals anhand seiner Zugangsdaten: Das Zugriffstoken, der Header Authorization und der erzeugte API-Schlüssel werden nie protokolliert.
Was der Server an die Skycloak-API sendet
Der gehostete Server und die lokale Binärdatei senden dieselben Header an die Skycloak-API (SKYCLOAK_ENDPOINT):
| Header | Wert | Zweck |
|---|---|---|
API-Key | dein API-Schlüssel oder der für die Sitzung erzeugte Schlüssel | authentifiziert die Anfrage |
API-Version | SKYCLOAK_API_VERSION | legt den API-Vertrag fest, für den der Server erstellt wurde |
User-Agent | skycloak-mcp/<version> | identifiziert den Client |
X-MCP-Tool | der registrierte Name des Tools, zum Beispiel skycloak_list_realms | gibt an, welches Tool die Anfrage gestellt hat |
X-MCP-Call-Id | eine zufällige UUID, die einmal pro Tool-Aufruf erzeugt wird | gruppiert alle Anfragen eines Aufrufs |
X-MCP-Tool und X-MCP-Call-Id werden nur bei Anfragen gesendet, die während der Ausführung eines Tool-Aufrufs gestellt werden. Ein Aufruf kann mehrere Anfragen auslösen: eine pro Cluster, wenn cluster_id nicht angegeben ist, und erneut, wenn ein 429 oder 5xx wiederholt wird. Alle verwenden dieselbe Aufruf-ID. Skycloak nutzt dieses Paar, um zu zählen, wie oft jedes Tool verwendet wird. So können wir entscheiden, welche Tools verbessert, dokumentiert oder eingestellt werden sollen. Die Header enthalten weder Argumente noch Ergebnisse oder sonstige Informationen über dich, die nicht bereits durch den API-Schlüssel bekannt sind. Sie werden ausschließlich an die Skycloak-API gesendet, niemals an deine Keycloak-Cluster oder an andere Stellen. Anfragen außerhalb eines Tool-Aufrufs, etwa bei der Anmeldung und beim Erstellen von API-Schlüsseln, enthalten keinen der beiden Header.
Konfiguration
| Env-Variable | Standardwert |
|---|---|
SKYCLOAK_API_KEY | keiner (optional für stdio; HTTP-Clients übermitteln stattdessen API-Key-Header) |
SKYCLOAK_ENDPOINT | https://api.skycloak.io |
SKYCLOAK_API_VERSION | aktuelle API-Version |
SKYCLOAK_ISSUER | https://login.app.skycloak.io/realms/skycloak (CLI-Anmeldung und der Autorisierungsserver, gegen den der HTTP-Transport Tokens verifiziert) |
SKYCLOAK_CLIENT_ID | skycloak-mcp (nur CLI-Gerätefluss) |
SKYCLOAK_DASHBOARD_URL | https://app.skycloak.io (erstellt CLI-Schlüssel und HTTP-Sitzungsschlüssel) |
SKYCLOAK_PUBLIC_URL | keiner (wird aus jeder Anfrage abgeleitet; setzen, wenn der Ingress Host umschreibt) |
OPENAI_APPS_CHALLENGE_TOKEN | Stellt das Verifizierungstoken für OpenAIs Plugin-Verzeichnis unter /.well-known/openai-apps-challenge bereit. Ist die Variable nicht gesetzt, liefert dieser Pfad 404. |
Befehle: init (Anmeldung im Browser), run (Server starten), logout (gespeicherten Schlüssel entfernen). init akzeptiert --workspace <id>, --allow-writes, --allow-credentials und --ttl-days (Standardwert 90).
| Flag | Standardwert | Beschreibung |
|---|---|---|
--transport | stdio | stdio oder http |
--http-addr | :8080 | Listen-Adresse für den HTTP-Transport |
--allow-writes | false | Aktiviert ändernde Tools für stdio und erlaubt HTTP-Sitzungen mit readonly=false, Schreib-Tools zu registrieren |
Entwicklung
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
Der API-Client unter internal/apiclient wird anhand der Skycloak-OpenAPI-
Spezifikation mit oapi-codegen generiert.
Mit der API synchron bleiben
Der Client in internal/apiclient wird mit oapi-codegen aus internal/apiclient/openapi.yaml generiert; führe make generate aus, um ihn zu aktualisieren. CI schlägt fehl, wenn der eingecheckte generierte Code von der Spezifikation abweicht. Anfragen werden bei 429/5xx mit Retry-After-bewusstem Backoff wiederholt.
Distribution
Wird bei jedem Tag als GitHub-Binärdateien und als ghcr.io/sky-cloak/skycloak-mcp-Container-Image veröffentlicht und als io.skycloak/skycloak-mcp in der MCP Registry bereitgestellt. Die meisten benötigen beides nicht: Für den gehosteten Server ist keine Installation erforderlich.
Plugin-Bundles
plugins/skycloak/ ist ein einzelner Ordner, der zwei Clients unterstützt: .antigravity-plugin/plugin.json mit mcp_config.json für Antigravity und .claude-plugin/plugin.json für Claude. Beide verweisen auf den gehosteten Server und enthalten die vier Skills, die bytegenaue Kopien von internal/tools/skills/ sind, da ein Installer nur diesen Ordner erhält.
plugin.json und mcp.json im Repository-Stammverzeichnis sind das Manifest Agent Plugins v1.0.0, das der awesome-copilot-Marketplace von GitHub einliest. Dieses Format erlaubt kein Logo-Feld, daher wird das Logo des Eintrags unter extensions["com.github.copilot"] geführt.
Das Feld version in diesen Manifesten und in .grok-plugin/plugin.json wird von CI anhand des Release-Tags gesetzt, da die Verzeichniseinträge main folgen. Der Abschnitt zu Verzeichnisaktualisierungen in der Plugin-README beschreibt dies.
Sicherheit
Bitte melde Sicherheitslücken vertraulich. Siehe SECURITY.md.
Mitwirkende
Entwickelt bei Skycloak von Guilliano Molaire, Neville Omangi und Aphilas. Der Repository-Verlauf wurde beim Öffnen des Repositories zusammengeführt, daher spiegelt das Commit-Protokoll nicht wider, wer was geschrieben hat.
Lizenz
Apache-2.0. Die OpenAPI-Beschreibung in internal/apiclient/openapi.yaml wird aus der Skycloak-
Plattform-API generiert und ist urheberrechtlich Skycloak zugeordnet; sie ist hier enthalten, damit der Client generiert und überprüft werden kann. Siehe NOTICE.