Skycloak
oficialServidor de Model Context Protocol para Skycloak Keycloak gestionado. Administre clústeres, reinos, aplicaciones, SSO y usuarios desde cualquier cliente MCP.
¿Qué puedes hacer con Skycloak MCP?
- Inventario y actualizaciones de clústeres — Enumera los clústeres, comprueba las versiones y consulta la ruta de actualización de cualquier clúster que esté desactualizado.
- Administración de realms y aplicaciones — Crea o actualiza realms y aplicaciones, asigna roles y rota los secretos de cliente de las aplicaciones.
- Configuración de proveedores de identidad — Añade proveedores de identidad OIDC a un realm, prueba la conexión y enumera las conexiones SSO existentes.
- Administración de usuarios y grupos — Enumera los usuarios, roles y grupos del realm; luego asigna roles o añade usuarios a grupos.
- Revisión de auditoría y eventos — Consulta eventos y registros de seguridad, o recupera los inicios de sesión fallidos recientes de un realm, agrupados por IP de origen.
- Destinos SIEM y de webhook — Crea un destino SIEM o una suscripción de webhook y envía un evento de prueba para confirmar la entrega.
Documentación
skycloak-mcp
Servidor oficial de Model Context Protocol para Skycloak (Keycloak gestionado): administra tus clústeres, realms, aplicaciones y SSO desde cualquier cliente MCP (Claude Desktop, Claude Code, Cursor).
Estado: versión preliminar. La cobertura de herramientas está creciendo; consulta el registro de cambios para ver qué está disponible.
Inicio rápido
claude mcp add --transport http skycloak https://mcp.skycloak.io
Sin clave de API, sin ID de cliente, sin configuración. Se abre el navegador, inicias sesión en Skycloak y aparecen las herramientas. Cualquier cliente MCP que admita HTTP transmisible funciona igual: indícale la URL y nada más.
Luego, pide algo:
- «¿Qué clústeres de Keycloak míos tienen actualizaciones pendientes?»
- «Crea un realm de staging en el clúster de la UE con inicio de sesión de Google y GitHub».
- «¿A quién se añadió al realm de producción durante la última semana?»
- «Configura un destino SIEM que reenvíe los eventos de administración a nuestro webhook de Datadog».
Autenticación y seguridad
- HTTP alojado, con OAuth (no hay credenciales que configurar). Apunta tu cliente a
https://mcp.skycloak.iosin encabezado. El servidor responde401con un enlace a sus metadatos RFC 9728 en/.well-known/oauth-protected-resource; el cliente ejecuta el flujo de autorización con código en el navegador contra el realm de inicio de sesión de Skycloak, y el token de acceso que recibe se intercambia por una clave de API de corta duración y limitada al espacio de trabajo, que usa la sesión. La clave dura una hora y se renueva automáticamente. No se guarda nada en la configuración del cliente. - HTTP alojado, con una clave de API. Crea una clave en el panel de Skycloak y envíala como
Authorization: Bearer <key>(oAPI-Key: <key>). Cada solicitud lleva sus propias credenciales y actúa únicamente en el espacio de trabajo de esas credenciales. El servidor no conserva el estado de la sesión, por lo que una solicitud nunca hereda las credenciales de otra persona. Las claves no se verifican antes de usarse: la autoridad es la API de Skycloak, así que una clave no válida genera un401en la primera llamada a una herramienta, no al conectarse. - Las herramientas se ajustan a tu rol. Con OAuth, la lista de herramientas se limita a las que permiten los ámbitos de la sesión, de modo que a un miembro de solo lectura del espacio de trabajo no se le muestran herramientas de escritura que responderían
403. Con una clave de API se registra toda la superficie, porque el servidor no puede ver los ámbitos de la clave, y una llamada no autorizada genera un403de la API. - stdio local. Ejecuta
skycloak-mcp inity autoriza en el navegador (flujo de autorización de dispositivo OAuth 2.0). Genera una clave de API limitada al espacio de trabajo, la guarda en el llavero del sistema operativo y detecta automáticamente tu espacio de trabajo predeterminado (pasa--workspace <id>para elegir otro).skycloak-mcp logoutelimina la clave guardada. - Sin interfaz / CI. Define la variable de entorno
SKYCLOAK_API_KEY(crea una clave en el panel de Skycloak) para omitir por completo el navegador. Siempre tiene prioridad sobre el llavero. - Las escrituras dependen de tus credenciales, no de una opción. El servidor alojado en
https://mcp.skycloak.iopermite operaciones de escritura, y lo que realmente puedes cambiar está limitado por los ámbitos de tu clave y tu rol en el espacio de trabajo: un miembro de solo lectura no puede modificar nada, independientemente de lo que indique la lista de herramientas. Añade?readonly=truea la URL para forzar una superficie de herramientas de solo lectura durante una sesión. El binario local funciona al revés y no registra herramientas de escritura a menos que se inicie con--allow-writes. - Las credenciales del clúster son opcionales.
get_cluster_credentialsdevuelve las credenciales de administrador de Keycloak de un clúster, que luego vería un asistente que tuviera la clave; por eso,initno solicita ese ámbito de forma predeterminada. Usa una clave que lo incluya: crea una en el panel o, mediante stdio, inicia sesión conskycloak-mcp init --allow-credentials. Sin ese ámbito, la herramienta devuelve un 403 que explica ambas opciones. - Las herramientas destructivas requieren confirmación: por ejemplo, eliminar un realm requiere un argumento
confirm=trueexplícito. - Las solicitudes tienen límites de frecuencia según tu plan de Skycloak; ante una respuesta
429, el servidor muestraRetry-After.
Herramientas
141 herramientas: 62 de solo lectura y 79 de escritura. Las herramientas de solo lectura siempre están disponibles. En el servidor alojado también se registran las herramientas de escritura, sujetas a los ámbitos de tus credenciales; el binario local solo las registra si se inicia con --allow-writes.
Los nombres de las herramientas llevan el prefijo skycloak_, que se omite en la tabla siguiente; por tanto, list_clusters es skycloak_list_clusters en tu cliente.
| Área | Solo lectura | Escritura (--allow-writes) |
|---|---|---|
| Clústeres | 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 |
| Seguridad perimetral | get_cluster_security, list_cluster_captcha_domains | update_cluster_security, add_cluster_captcha_domain, remove_cluster_captcha_domain |
| Realms | list_realms, get_realm | create_realm, update_realm, delete_realm |
| Aplicaciones | 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 |
| Proveedores de identidad | 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 |
| Usuarios, roles y grupos | 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 |
| Dominios personalizados | 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 |
| Marca y temas | 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 |
| Extensiones | list_extensions, list_cluster_extensions | install_extension, upgrade_extension, update_extension, uninstall_extension, delete_extension |
| SMTP | get_smtp | upsert_smtp, delete_smtp, test_smtp |
| Exportaciones y registros | list_exports, get_export, get_logs, get_security_logs, query_events | create_export, delete_export, export_cluster_events |
| Importación y exportación de realms | 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 |
Convenciones: las herramientas destructivas (delete_*, uninstall_extension, cancel_cluster_upgrade, update_theme_content, update_theme_settings, restart_cluster_instances) requieren confirm=true. update_theme_settings activa o desactiva exact_theme_names para el espacio de trabajo; la clave de API del usuario debe haberse generado para un propietario o administrador del espacio de trabajo, o recibirá 403 incluso con themes:write. Al activarlo, los temas existentes pasan en segundo plano a sus nombres exactos de publicación; un tema cuyo contenido se haya reemplazado con su nombre exacto informa restart_required: true desde get_theme/list_themes/update_theme_content hasta que restart_cluster_instances reinicie las instancias de Keycloak de ese clúster. El reinicio puede aplazarse hasta la ventana de mantenimiento del clúster en lugar de aplicarse de inmediato; esto se indica con deferred: true y, cuando se conoce, con next_window. create_cluster es asíncrono: consulta get_cluster hasta que el clúster esté available. create_domain devuelve los registros DNS que debe crear el cliente; verify_domain inicia una comprobación de DNS. set_theme_assignment activa un tema personalizado por tipo de tema de Keycloak (una cadena vacía restablece el valor predeterminado integrado). update_theme_content reemplaza el archivo del tema en el mismo lugar (ZIP en base64 o JAR de Keycloakify en content_base64), conservando el ID, el nombre y las asignaciones del tema a realms y aplicaciones, de modo que editar un tema ya no requiere eliminarlo y volver a cargarlo; requiere confirm=true porque el archivo que sobrescribe no se puede recuperar, y update_theme sigue cambiando únicamente el nombre, la descripción y la versión. Consulta docs/theme-content-update.md para saber cómo se realiza esa llamada. update_cluster_security deja intacta la configuración de CAPTCHA. La importación y exportación de realms mueve la configuración de un realm y es independiente de create_export, que vuelca la base de datos de todo un clúster: ambas operaciones son asíncronas y el archivo del realm siempre está cifrado, por lo que se necesita la contraseña usada para exportarlo para volver a importarlo. Se puede importar un realm directamente desde una exportación existente (source_export_id) o desde un archivo cargado (create_realm_import_upload_url, PUT y luego upload_s3_key); la importación crea un realm y rechaza los nombres duplicados en lugar de sobrescribirlos, y requiere confirm=true porque también incorpora usuarios y credenciales.
Instancias de OpenFGA: todas las herramientas de OpenFGA requieren cluster_id. create_openfga_instance vincula una instancia de OpenFGA a un realm del clúster; cada realm puede tener como máximo una. Devuelve 403 cuando el plan del espacio de trabajo no incluye OpenFGA o se alcanzó el límite de instancias, 409 cuando el realm ya tiene una instancia y 422 cuando el realm está master, no existe o está deshabilitado. Es asíncrono: consulta get_openfga_instance hasta que status sea ready o failed. La instancia solo acepta tokens de ese realm que incluyan su audiencia, y get_openfga_instance devuelve api_url, issuer y audience para usarla. El asignador de audiencia que añade la audiencia a los tokens del realm se incorpora en Keycloak. Las operaciones de listado y eliminación funcionan sin acceso a OpenFGA. delete_openfga_instance elimina la implementación, la ruta y la base de datos, y los datos de autorización que contiene no se pueden recuperar; la instancia muestra deleting hasta que desaparece.
Ubicaciones de los clústeres: location en create_cluster, y en los valores que devuelven list_clusters, get_cluster y list_cluster_locations, es uno de us (este de EE. UU.), us-west (oeste de EE. UU.), ca (Canadá), eu (Europa) o au (Australia), sin distinguir mayúsculas y minúsculas. us siempre significa este de EE. UU. us-west solo está disponible para los espacios de trabajo a los que se les haya concedido acceso: list_cluster_locations muestra todas las ubicaciones con available establecido para tu espacio de trabajo, y crear un clúster en una ubicación que no puedes usar devuelve el error de la API 400 «location not available».
Indicaciones
Ocho indicaciones te ofrecen un punto de partida para explorar estas herramientas. Los clientes las muestran como comandos de barra o acciones sugeridas; cada una acepta argumentos (realm, clúster, intervalo de tiempo) y guía al modelo para que use las herramientas adecuadas en el orden correcto.
| Prompt | Qué hace |
|---|---|
audit_self_registration | Encuentra todos los realms que aún permiten el autorregistro, en un clúster o en todos |
review_upgrades | Detecta los clústeres que tienen una versión de Keycloak desactualizada y describe la ruta de actualización |
triage_failed_logins | Obtiene los inicios de sesión fallidos recientes de un realm y los agrupa por IP de origen |
review_identity_providers | Enumera las conexiones SSO de un realm y comprueba si una específica está habilitada |
review_admin_changes | Muestra quién cambió qué recientemente en un realm, centrándose en la configuración de inicio de sesión y seguridad |
provision_environment | Crea un clúster, añade un realm y configura un proveedor de identidad, confirmando cada paso |
set_up_custom_domain | Añade un dominio personalizado, devuelve los registros DNS exactos, los verifica y lo dirige a un realm |
rotate_client_secret | Regenera el secreto de cliente de una aplicación, explicando primero el alcance del impacto |
Los prompts están sujetos a las mismas restricciones que las herramientas que mencionan: los tres que realizan cambios solo se ofrecen a las sesiones que podrían llamar a las herramientas de escritura a las que hacen referencia, y sus instrucciones indican al modelo que te pida confirmación antes de cambiar nada. El requisito confirm=true para las herramientas destructivas sigue aplicándose además de esto.
Skills
Mientras que un prompt sirve como punto de partida, una skill es un manual operativo completo que el modelo carga cuando lo necesita. El servidor incluye cuatro, disponibles mediante la extensión preliminar SEP-2640 Skills: declara io.modelcontextprotocol/skills en sus capacidades, responde a skills/list y skills/get, y ofrece cada SKILL.md como un recurso ordinario en skill://<name>/SKILL.md con un resumen sha256 en su entrada de listado. El directorio de plugins de OpenAI importa las skills exactamente con este formato.
| Skill | Qué codifica |
|---|---|
auth-incident-triage | Clasifica el problema «los usuarios no pueden iniciar sesión»: distingue las interrupciones de la plataforma de los ataques y de los cambios de configuración, usando eventos, registros de WAF y el estado del clúster. Solo lectura |
enterprise-sso-rollout | Conecta un IdP empresarial a un realm de principio a fin: validación del emisor, registro de la aplicación upstream, configuración del broker, pruebas de conexión y verificación con eventos de inicio de sesión reales |
keycloak-migration-doctor | Comprueba antes de la ejecución una exportación, importación o migración de Keycloak frente a los obstáculos que el equipo de soporte encuentra realmente (políticas de scripts, la ruta heredada /auth, expectativas de exportación parcial) y diagnostica un trabajo fallido leyendo su error_message real en lugar del aviso genérico del panel |
keycloak-upgrade-readiness | Evalúa las diferencias de versión, determina qué rompe la nueva versión de Keycloak (extensiones, temas) y secuencia el despliegue entre entornos con una exportación como plan de reversión |
Las skills siguen las mismas restricciones que las herramientas que mencionan: los tres flujos de trabajo basados en herramientas de escritura no se ofrecen a las sesiones de solo lectura, y a una sesión con alcance limitado solo se le ofrece una skill cuyas herramientas tenga disponibles. Las fuentes están en internal/tools/skills/, en un directorio por skill y en el formato estándar Agent Skills, por lo que también funcionan si se copian directamente a un directorio local de skills.
Conexión
Para HTTP alojado, la opción más sencilla es OAuth, que no requiere credenciales:
claude mcp add --transport http skycloak https://mcp.skycloak.io
La primera llamada abre el navegador; apruebas el acceso en la página de inicio de sesión de Skycloak y aparecen las herramientas. Si perteneces a más de un espacio de trabajo, indica cuál quieres usar:
claude mcp add --transport http skycloak "https://mcp.skycloak.io?workspace=<workspace-id>"
De lo contrario, crea una clave de API en el panel de Skycloak y configura tu cliente MCP para que la envíe como token bearer:
claude mcp add --transport http skycloak https://mcp.skycloak.io --header "Authorization: Bearer sk_sc_XXX"
Esto añade lo siguiente a .claude.json:
{
"mcpServers": {
"skycloak": {
"type": "http",
"url": "https://mcp.skycloak.io",
"headers": {
"Authorization": "Bearer sk_sc_XXX"
}
}
}
}
Gemini CLI instala el servidor alojado como una extensión, a partir del manifiesto de este repositorio:
gemini extensions install https://github.com/sky-cloak/skycloak-mcp
Antigravity instala el servidor alojado como un plugin, a partir del paquete de plugins/skycloak/:
agy plugin install ./plugins/skycloak
Copilot CLI lo instala desde el manifiesto Agent Plugins en la raíz del repositorio, una vez aprobada la entrada:
copilot plugin install skycloak@awesome-copilot
Para stdio local, inicia sesión una vez y luego apunta tu cliente a skycloak-mcp run:
skycloak-mcp init # one-time browser sign-in; stores a key in your keychain
Claude Desktop / Cursor (local, stdio):
{
"mcpServers": {
"skycloak": {
"command": "skycloak-mcp",
"args": ["run", "--transport", "stdio"]
}
}
}
Claude Code:
claude mcp add skycloak -- skycloak-mcp run --transport stdio
Para ejecución sin interfaz / CI (sin navegador), omite init y pasa la clave en su lugar: añade "env": { "SKYCLOAK_API_KEY": "sk_sc_..." } a la configuración o claude mcp add skycloak --env SKYCLOAK_API_KEY=sk_sc_... -- skycloak-mcp run --transport stdio.
Añade --allow-writes solo si tienes intención de hacer cambios (inicia sesión con skycloak-mcp init --allow-writes o usa una clave con alcance de escritura).
Añade ?readonly=true a una URL HTTP alojada para exponer solo herramientas de lectura en esa sesión HTTP, o ?readonly=false para solicitar la superficie de herramientas con capacidad de escritura. El parámetro de consulta tiene como valor predeterminado false, pero las herramientas de escritura solo se registran si el servidor se inició con --allow-writes.
Añade ?workspace=<uuid> para elegir el espacio de trabajo en el que actúa una sesión OAuth. Solo es necesario si perteneces a más de uno; si tienes un único espacio de trabajo, el servidor lo elige por ti. Si perteneces a varios y no indicas ninguno, la conexión falla con un mensaje que los enumera.
Ejecución del transporte HTTP
skycloak-mcp run --transport http --http-addr :8080
No necesita credenciales propias: quienes llaman proporcionan las suyas en cada solicitud, así que no se inyecta nada durante el despliegue. GET /healthz y GET /readyz no requieren autenticación e informan únicamente de que el proceso está activo; deliberadamente no comprueban la API de Skycloak, para que una interrupción del servicio upstream no haga fallar a la vez las comprobaciones de todas las réplicas. El servidor no mantiene estado de sesión, por lo que las réplicas no necesitan afinidad de sesión y se pueden escalar o reiniciar libremente. SIGTERM deja de aceptar conexiones nuevas y permite que terminen las llamadas en curso.
La ruta OAuth está activa cuando se configuran SKYCLOAK_ISSUER y SKYCLOAK_DASHBOARD_URL, como ocurre de forma predeterminada. En ese caso, GET /.well-known/oauth-protected-resource se sirve sin autenticación e identifica el realm como servidor de autorización. Su valor resource se obtiene de SKYCLOAK_PUBLIC_URL si está configurado y, de lo contrario, de Host y del esquema de la propia solicitud, por lo que un despliegue en un único host detrás de un ingress no necesita configuración adicional. El esquema se obtiene de X-Forwarded-Proto cuando está presente y, de lo contrario, el valor predeterminado es https para cualquier host que no sea de loopback, ya que TLS termina upstream y publicar un identificador http:// no coincidiría con la URL a la que se conectó el cliente. Configura SKYCLOAK_PUBLIC_URL si tu ingress reescribe Host. El documento también incluye openid profile email como su scopes_supported, y el desafío WWW-Authenticate los repite como parámetro scope, de modo que un cliente que lea cualquiera de los dos los solicita al realm: openid es obligatorio, porque el intercambio de tokens hace que el panel llame al endpoint userinfo de Keycloak, y Keycloak rechaza los tokens concedidos sin ese valor. Si un token llega sin él, se rechaza durante la verificación con un 401 y el desafío, en lugar de pasar a un intercambio que no puede completarse; así, un cliente que aún conserve una concesión anterior deja de reintentarlo y vuelve a iniciar sesión. Si se deja en blanco cualquiera de las variables del emisor o del panel, OAuth se desactiva por completo y el servidor vuelve a solicitar una clave de API, sin ofrecer nada más.
OPENAI_APPS_CHALLENGE_TOKEN sirve el token de verificación del dominio del directorio de plugins de OpenAI en /.well-known/openai-apps-challenge, como texto sin formato y sin nada más. Si no está configurado, la ruta no se registra y devuelve 404.
Al iniciarse, el servidor registra una línea con la configuración que resolvió (oauth=, issuer=, dashboard=, public_url=, endpoint=, allow_writes=), para que se pueda detectar una configuración incorrecta sin volver a desplegar. Cada solicitud rechazada en la ruta OAuth registra una línea que indica la etapa que falló (verify, exchange o scopes), el estado que recibió quien hizo la llamada y el error subyacente. Si falla la verificación, se añade la comprobación que rechazó el token (expired, wrong_issuer, bad_signature, unknown_key_id, wrong_token_type, no_openid_scope, entre otras); si falla el intercambio, se añade el estado del panel y el host al que se llamó. Una vez verificado, quien hizo la llamada aparece como el sujeto del token, nunca como una credencial: no se registran el token de acceso, el encabezado Authorization ni la clave de API generada.
Lo que el servidor envía a la API de Skycloak
El servidor alojado y el binario local envían los mismos encabezados a la API de Skycloak (SKYCLOAK_ENDPOINT):
| Encabezado | Valor | Motivo |
|---|---|---|
API-Key | tu clave de API o la clave generada para la sesión | autentica la solicitud |
API-Version | SKYCLOAK_API_VERSION | fija el contrato de API para el que se compiló el servidor |
User-Agent | skycloak-mcp/<version> | identifica al cliente |
X-MCP-Tool | el nombre registrado de la herramienta, por ejemplo skycloak_list_realms | indica qué herramienta hizo la solicitud |
X-MCP-Call-Id | un UUID aleatorio generado una vez por llamada a una herramienta | agrupa todas las solicitudes de una llamada |
X-MCP-Tool y X-MCP-Call-Id solo se envían en las solicitudes realizadas al atender una llamada a una herramienta. Una llamada puede realizar varias solicitudes: una por clúster cuando se omite cluster_id, y de nuevo cuando se reintenta un 429 o un 5xx; todas comparten el ID de la llamada. Skycloak usa este par para contar la frecuencia de uso de cada herramienta, lo que nos indica cuáles debemos mejorar, documentar o retirar. No contienen argumentos, resultados ni información sobre ti más allá de lo que ya identifica la clave de API, y solo se envían a la API de Skycloak, nunca a tus clústeres de Keycloak ni a ningún otro lugar. Las solicitudes realizadas fuera de una llamada a una herramienta, como iniciar sesión y generar claves de API, no incluyen ninguno de los dos.
Configuración
| Variable de entorno | Valor predeterminado |
|---|---|
SKYCLOAK_API_KEY | ninguno (opcional para stdio; los clientes HTTP proporcionan encabezados API-Key en su lugar) |
SKYCLOAK_ENDPOINT | https://api.skycloak.io |
SKYCLOAK_API_VERSION | versión actual de la API |
SKYCLOAK_ISSUER | https://login.app.skycloak.io/realms/skycloak (inicio de sesión de CLI y servidor de autorización contra el que el transporte HTTP verifica los tokens) |
SKYCLOAK_CLIENT_ID | skycloak-mcp (solo flujo de dispositivo de CLI) |
SKYCLOAK_DASHBOARD_URL | https://app.skycloak.io (genera claves para CLI y sesiones HTTP) |
SKYCLOAK_PUBLIC_URL | ninguno (se deriva de cada solicitud; configúralo cuando el ingress reescriba Host) |
OPENAI_APPS_CHALLENGE_TOKEN | Sirve el token de verificación del directorio de plugins de OpenAI en /.well-known/openai-apps-challenge. Si no está configurado, esa ruta devuelve 404. |
Comandos: init (inicio de sesión en el navegador), run (servir), logout (eliminar la clave almacenada). init acepta --workspace <id>, --allow-writes, --allow-credentials y --ttl-days (valor predeterminado: 90).
| Opción | Valor predeterminado | Descripción |
|---|---|---|
--transport | stdio | stdio o http |
--http-addr | :8080 | dirección de escucha del transporte HTTP |
--allow-writes | false | habilita las herramientas que realizan cambios para stdio y permite que las sesiones HTTP con readonly=false registren herramientas de escritura |
Desarrollo
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
El cliente de API en internal/apiclient se genera a partir de la especificación OpenAPI de Skycloak con oapi-codegen.
Mantener la sincronización con la API
El cliente en internal/apiclient se genera a partir de internal/apiclient/openapi.yaml con oapi-codegen; ejecuta make generate para actualizarlo. CI falla si el código generado confirmado difiere de la especificación. Las solicitudes se reintentan ante 429/5xx con una espera progresiva que tiene en cuenta Retry-After.
Distribución
Se publica como binarios de GitHub y una imagen de contenedor ghcr.io/sky-cloak/skycloak-mcp con cada etiqueta, y en el MCP Registry como io.skycloak/skycloak-mcp. La mayoría de las personas no necesita ninguna de las dos opciones: el servidor alojado no requiere instalación.
Paquetes de plugins
plugins/skycloak/ es una carpeta que sirve a dos clientes: .antigravity-plugin/plugin.json con mcp_config.json para Antigravity, y .claude-plugin/plugin.json para Claude. Ambos apuntan al servidor alojado e incluyen las cuatro skills, que son copias idénticas byte por byte de internal/tools/skills/, ya que el instalador solo recibe esa carpeta.
Los archivos plugin.json y mcp.json en la raíz del repositorio son el manifiesto de Agent Plugins v1.0.0 que utiliza el marketplace awesome-copilot de GitHub. Ese formato no permite un campo para el logotipo, así que el logotipo del listado se incluye en extensions["com.github.copilot"].
El campo version de esos manifiestos y de .grok-plugin/plugin.json se establece a partir de la etiqueta de la versión mediante CI, porque los listados del directorio siguen main. La sección sobre actualizaciones del directorio del README del plugin lo describe.
Seguridad
Informa de las vulnerabilidades de forma privada. Consulta SECURITY.md.
Colaboradores
Creado en Skycloak por Guilliano Molaire, Neville Omangi y Aphilas. El historial del repositorio se fusionó al hacerse público, por lo que el registro de confirmaciones no refleja quién escribió cada parte.
Licencia
Apache-2.0. La descripción de OpenAPI en internal/apiclient/openapi.yaml se genera a partir de la API de la plataforma Skycloak y es propiedad de Skycloak; se incluye aquí para que el cliente pueda generarse y verificarse. Consulta NOTICE.