Skycloak

oficial

Servidor 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

Smithery

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.io sin encabezado. El servidor responde 401 con 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> (o API-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 un 401 en 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 un 403 de la API.
  • stdio local. Ejecuta skycloak-mcp init y 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 logout elimina 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.io permite 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=true a 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_credentials devuelve las credenciales de administrador de Keycloak de un clúster, que luego vería un asistente que tuviera la clave; por eso, init no solicita ese ámbito de forma predeterminada. Usa una clave que lo incluya: crea una en el panel o, mediante stdio, inicia sesión con skycloak-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=true explícito.
  • Las solicitudes tienen límites de frecuencia según tu plan de Skycloak; ante una respuesta 429, el servidor muestra Retry-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.

ÁreaSolo lecturaEscritura (--allow-writes)
Clústereslist_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_windowcreate_cluster, update_cluster, delete_cluster, cancel_cluster_upgrade, restart_cluster_instances, set_cluster_maintenance_window, delete_cluster_maintenance_window
Seguridad perimetralget_cluster_security, list_cluster_captcha_domainsupdate_cluster_security, add_cluster_captcha_domain, remove_cluster_captcha_domain
Realmslist_realms, get_realmcreate_realm, update_realm, delete_realm
Aplicacioneslist_applications, get_application, list_application_roles, list_application_sessionscreate_application, update_application, delete_application, assign_application_role, remove_application_role, rotate_application_secret
Proveedores de identidadlist_identity_providers, get_identity_provider, list_identity_provider_templates, discover_oidccreate_identity_provider (OIDC), update_identity_provider, delete_identity_provider, test_identity_provider
Usuarios, roles y gruposlist_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_groupscreate_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 personalizadoslist_domains, get_domain, list_domain_routes, get_domain_routecreate_domain, verify_domain, delete_domain, create_domain_route, update_domain_route, delete_domain_route
Marca y temaslist_themes, get_theme, get_theme_assignment, get_client_theme_assignment, get_login_branding, get_email_branding, download_theme_content, get_theme_settingsset_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
Extensioneslist_extensions, list_cluster_extensionsinstall_extension, upgrade_extension, update_extension, uninstall_extension, delete_extension
SMTPget_smtpupsert_smtp, delete_smtp, test_smtp
Exportaciones y registroslist_exports, get_export, get_logs, get_security_logs, query_eventscreate_export, delete_export, export_cluster_events
Importación y exportación de realmsget_realm_export, get_realm_importcreate_realm_export, create_realm_import, create_realm_import_upload_url
SIEMlist_siem_destinations, get_siem_destinationcreate_siem_destination, update_siem_destination, delete_siem_destination, test_siem_destination
Webhookslist_webhook_event_types, list_webhook_subscriptions, get_webhook_subscriptioncreate_webhook_subscription, update_webhook_subscription, delete_webhook_subscription, test_webhook_subscription
OpenFGAlist_openfga_instances, get_openfga_instancecreate_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.

PromptQué hace
audit_self_registrationEncuentra todos los realms que aún permiten el autorregistro, en un clúster o en todos
review_upgradesDetecta los clústeres que tienen una versión de Keycloak desactualizada y describe la ruta de actualización
triage_failed_loginsObtiene los inicios de sesión fallidos recientes de un realm y los agrupa por IP de origen
review_identity_providersEnumera las conexiones SSO de un realm y comprueba si una específica está habilitada
review_admin_changesMuestra quién cambió qué recientemente en un realm, centrándose en la configuración de inicio de sesión y seguridad
provision_environmentCrea un clúster, añade un realm y configura un proveedor de identidad, confirmando cada paso
set_up_custom_domainAñade un dominio personalizado, devuelve los registros DNS exactos, los verifica y lo dirige a un realm
rotate_client_secretRegenera 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.

SkillQué codifica
auth-incident-triageClasifica 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-rolloutConecta 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-doctorComprueba 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-readinessEvalú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):

EncabezadoValorMotivo
API-Keytu clave de API o la clave generada para la sesiónautentica la solicitud
API-VersionSKYCLOAK_API_VERSIONfija el contrato de API para el que se compiló el servidor
User-Agentskycloak-mcp/<version>identifica al cliente
X-MCP-Toolel nombre registrado de la herramienta, por ejemplo skycloak_list_realmsindica qué herramienta hizo la solicitud
X-MCP-Call-Idun UUID aleatorio generado una vez por llamada a una herramientaagrupa 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 entornoValor predeterminado
SKYCLOAK_API_KEYninguno (opcional para stdio; los clientes HTTP proporcionan encabezados API-Key en su lugar)
SKYCLOAK_ENDPOINThttps://api.skycloak.io
SKYCLOAK_API_VERSIONversión actual de la API
SKYCLOAK_ISSUERhttps://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_IDskycloak-mcp (solo flujo de dispositivo de CLI)
SKYCLOAK_DASHBOARD_URLhttps://app.skycloak.io (genera claves para CLI y sesiones HTTP)
SKYCLOAK_PUBLIC_URLninguno (se deriva de cada solicitud; configúralo cuando el ingress reescriba Host)
OPENAI_APPS_CHALLENGE_TOKENSirve 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ónValor predeterminadoDescripción
--transportstdiostdio o http
--http-addr:8080dirección de escucha del transporte HTTP
--allow-writesfalsehabilita 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.