Skycloak
oficialServidor do Model Context Protocol para o Keycloak gerenciado pela Skycloak. Gerencie clusters, realms, aplicativos, SSO e usuários a partir de qualquer cliente MCP.
O que você pode fazer com Skycloak MCP?
- Inventário de clusters e status de atualização — Liste seus clusters do Keycloak, verifique quais estão com atualizações pendentes e obtenha o caminho de atualização de cada um.
- Gerenciamento de realms e aplicações — Crie ou atualize realms e aplicações, gerencie funções de aplicação e alterne os segredos de cliente.
- Configuração de provedores de identidade — Adicione provedores de identidade OIDC a um realm, teste a conexão e revise as conexões SSO existentes.
- Revisão de usuários e acessos — Liste usuários, funções e grupos do realm e consulte eventos para ver quem foi adicionado ou o que mudou recentemente.
- Destinos de SIEM e webhooks — Crie e teste destinos de SIEM ou assinaturas de webhook que encaminham eventos administrativos para um endpoint externo.
- Fluxos de trabalho guiados — Execute prompts como
review_upgradesoutriage_failed_logins, que orientam você pelas ferramentas certas na ordem adequada.
Documentação
skycloak-mcp
Servidor oficial do Model Context Protocol para Skycloak (Keycloak gerenciado): gerencie seus clusters, realms, aplicações e SSO em qualquer cliente MCP (Claude Desktop, Claude Code, Cursor).
Status: versão inicial. A cobertura de ferramentas está crescendo; consulte o changelog para saber o que está disponível.
Início rápido
claude mcp add --transport http skycloak https://mcp.skycloak.io
Sem chave de API, sem ID de cliente, sem configuração. Seu navegador abre, você entra no Skycloak e as ferramentas aparecem. Qualquer cliente MCP compatível com HTTP transmitível funciona da mesma forma: informe a URL e nada mais.
Em seguida, peça algo:
- "Quais dos meus clusters Keycloak estão com atualizações atrasadas?"
- "Crie um realm de staging no cluster da UE com login do Google e do GitHub."
- "Quem foi adicionado ao realm de produção na última semana?"
- "Configure um destino SIEM que encaminhe eventos administrativos para nosso webhook do Datadog."
Autenticação e segurança
- HTTP hospedado, com OAuth (sem credenciais para configurar). Aponte seu cliente para
https://mcp.skycloak.iosem cabeçalho. O servidor responde401com uma referência aos metadados RFC 9728 em/.well-known/oauth-protected-resource, o cliente executa o fluxo de código de autorização no navegador usando o realm de login do Skycloak, e o token de acesso recebido é trocado por uma chave de API de curta duração, com escopo de workspace, que será usada pela sessão. A chave dura uma hora e é renovada automaticamente. Nada é armazenado na configuração do cliente. - HTTP hospedado, com uma chave de API. Crie uma chave no painel do Skycloak e envie-a como
Authorization: Bearer <key>(ouAPI-Key: <key>). Cada solicitação leva sua própria credencial e atua somente no workspace dessa credencial. O servidor não mantém estado de sessão, portanto uma solicitação nunca herda a credencial de outro chamador. As chaves não são verificadas antes do uso: a API do Skycloak é a autoridade, então uma chave inválida resulta em401na primeira chamada de ferramenta, e não no momento da conexão. - As ferramentas correspondem à sua função. Com OAuth, a lista de ferramentas é reduzida ao que os escopos da sessão permitem, para que um membro do workspace somente leitura não veja ferramentas de escrita que resultariam em
403. Com uma chave de API, toda a superfície é registrada, pois os escopos da chave não são visíveis ao servidor, e uma chamada não autorizada resulta em403da API. - stdio local. Execute
skycloak-mcp inite aprove no navegador (fluxo de autorização de dispositivo OAuth 2.0). Ele gera uma chave de API com escopo de workspace, armazena-a no chaveiro do sistema operacional e detecta automaticamente seu workspace padrão (passe--workspace <id>para escolher outro).skycloak-mcp logoutremove a chave armazenada. - Sem interface / CI. Defina a variável de ambiente
SKYCLOAK_API_KEY(crie uma chave no painel do Skycloak) para ignorar completamente o navegador. Ela sempre tem precedência sobre o chaveiro. Sem chave e sem chaveiro acessível — em um contêiner ou em qualquer host sem um Secret Service — o servidor stdio ainda inicia e lista suas ferramentas, permitindo que um diretório faça introspecção; cada chamada então falha com um erro que informa as duas formas de fornecer uma credencial. - As gravações são controladas pela sua credencial, não por uma flag. O servidor hospedado em
https://mcp.skycloak.iopermite gravações, e o que você pode realmente alterar é limitado pelos escopos da sua chave e pela sua função no workspace: um membro somente leitura não pode modificar nada, independentemente do que a lista de ferramentas indicar. Adicione?readonly=trueà URL para forçar uma superfície de ferramentas somente leitura para uma sessão. O binário local funciona de forma oposta e não registra ferramentas de gravação, a menos que seja iniciado com--allow-writes. - As credenciais do cluster são opcionais.
get_cluster_credentialsretorna as credenciais de administrador do Keycloak de um cluster, que ficariam visíveis para um assistente que tivesse a chave; por isso,initnão solicita esse escopo por padrão. Use uma chave que o inclua: crie uma no painel ou, via stdio, entre comskycloak-mcp init --allow-credentials. Sem esse escopo, a ferramenta retorna um 403 que explica as duas opções. - Ferramentas destrutivas exigem confirmação: excluir um realm, por exemplo, requer um argumento
confirm=trueexplícito. - As solicitações têm limite de taxa de acordo com seu plano Skycloak; em uma resposta
429, o servidor apresentaRetry-After.
Ferramentas
143 ferramentas: 63 somente leitura e 80 de gravação. As ferramentas somente leitura estão sempre disponíveis. No servidor hospedado, as ferramentas de gravação também são registradas e controladas pelos escopos da sua credencial; o binário local só as registra quando iniciado com --allow-writes.
Os nomes das ferramentas têm o prefixo skycloak_, omitido na tabela abaixo; portanto, list_clusters corresponde a skycloak_list_clusters no seu cliente.
| Área | Somente leitura | Gravação (--allow-writes) |
|---|---|---|
| Clusters | 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 |
| Segurança de borda | get_cluster_security, list_cluster_captcha_domains | update_cluster_security, add_cluster_captcha_domain, remove_cluster_captcha_domain |
| Link privado | get_cluster_private_link | update_cluster_private_link |
| Realms | list_realms, get_realm | create_realm, update_realm, delete_realm |
| Aplicações | 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 |
| Provedores de identidade | 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 |
| Usuários, funções e 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 |
| Domínios 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 e 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 |
| Extensões | list_extensions, list_cluster_extensions | install_extension, upgrade_extension, update_extension, uninstall_extension, delete_extension |
| SMTP | get_smtp | upsert_smtp, delete_smtp, test_smtp |
| Exportações e logs | list_exports, get_export, get_logs, get_security_logs, query_events | create_export, delete_export, export_cluster_events |
| Importação e exportação 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 |
Convenções: ferramentas destrutivas (delete_*, uninstall_extension, cancel_cluster_upgrade, update_theme_content, update_theme_settings, restart_cluster_instances) exigem confirm=true. update_theme_settings ativa ou desativa exact_theme_names para o workspace; a chave de API do chamador precisa ter sido gerada para um proprietário ou administrador do workspace, caso contrário, a chamada retorna 403, mesmo com themes:write. Ao ativá-la, os temas existentes são movidos em segundo plano para os nomes exatos usados para servi-los; um tema cujo conteúdo foi substituído sob seu nome exato retorna restart_required: true de get_theme/list_themes/update_theme_content até que restart_cluster_instances reinicie as instâncias Keycloak do cluster. A reinicialização pode ser adiada para a janela de manutenção do cluster em vez de ser aplicada imediatamente; isso é informado como deferred: true e, quando conhecido, next_window. create_cluster é assíncrono: consulte get_cluster até que o cluster esteja available. create_domain retorna os registros DNS que o cliente precisa criar; verify_domain inicia uma verificação de DNS. set_theme_assignment ativa um tema personalizado por tipo de tema do Keycloak (uma string vazia restaura o padrão integrado). update_theme_content substitui o arquivo compactado de um tema no mesmo local (ZIP em base64 ou JAR do Keycloakify em content_base64), mantendo o ID, o nome, o realm e as atribuições a aplicações do tema, para que editar um tema não exija mais excluí-lo e carregá-lo novamente; é necessário confirm=true, pois o arquivo compactado substituído não pode ser recuperado, e update_theme continua alterando apenas o nome, a descrição e a versão. Consulte docs/theme-content-update.md para saber como fazer essa chamada. update_cluster_security não altera as configurações de CAPTCHA. get_realm retorna o frontend_url do realm, quando definido, e update_realm o define ou, se receber uma string vazia, o limpa, mantendo as demais configurações do realm; alterá-lo muda o emissor do realm, seus links e a origem das passkeys. A API recusa com 403 em um cluster que não seja dedicado, com 422 para o realm master ou para uma URL inválida, e com 409 para um realm servido em um domínio personalizado; a ferramenta retorna a recusa sem alterações. update_cluster_private_link define os IDs de assinatura do Azure autorizados a se conectar ao link privado de um cluster e retorna o novo estado: a lista substitui a armazenada, uma lista vazia a limpa, e omiti-la ou usar enabled mantém essa parte inalterada. A API recusa com 403 quando o plano não inclui rede privada, com 422 quando o site do cluster não tem um link privado do Azure ou um ID não é um GUID válido, e com 409 ao desativar o link privado enquanto o acesso público está desativado; a ferramenta retorna a recusa sem alterações. A importação/exportação de realms transfere a configuração de um realm e é separada de create_export, que despeja o banco de dados de um cluster inteiro: ambas são assíncronas, e o arquivo do realm é sempre criptografado, portanto a senha usada para exportá-lo é necessária para importá-lo novamente. Um realm pode ser importado diretamente de uma exportação existente (source_export_id) ou de um arquivo carregado (create_realm_import_upload_url, PUT e, em seguida, upload_s3_key); a importação cria um realm e recusa nomes duplicados em vez de sobrescrevê-los, e exige confirm=true, pois também importa usuários e credenciais.
Instâncias OpenFGA: todas as ferramentas OpenFGA recebem cluster_id. create_openfga_instance associa uma instância OpenFGA a um único realm do cluster; cada realm pode ter no máximo uma. Retorna 403 quando o plano do workspace não inclui OpenFGA ou o workspace atingiu o limite de instâncias, 409 quando o realm já tem uma instância e 422 quando o realm está master, não existe ou está desativado. É assíncrono: consulte get_openfga_instance até que status esteja ready ou failed. A instância aceita apenas tokens desse realm que incluam seu público, e get_openfga_instance retorna api_url, issuer e audience para chamá-la. O mapeador de público que inclui o público nos tokens do realm é adicionado no Keycloak. A listagem e a exclusão funcionam sem acesso ao OpenFGA. delete_openfga_instance remove a implantação, a rota e o banco de dados, e os dados de autorização nele contidos não podem ser recuperados; a instância aparece como deleting até ser removida.
Localizações dos clusters: location em create_cluster, e em qualquer valor retornado por list_clusters, get_cluster e list_cluster_locations, é um de us (US East), us-west (US West), ca (Canadá), eu (Europa) ou au (Austrália), sem distinção entre maiúsculas e minúsculas. us sempre significa US East. us-west só está disponível para workspaces aos quais foi concedido acesso: list_cluster_locations lista todas as localizações com available definido para seu workspace, e criar um cluster em uma localização que você não pode usar retorna o erro da API 400 "location not available".
Prompts
Oito prompts oferecem um ponto de partida para essa superfície de ferramentas. Os clientes os exibem como comandos de barra ou ações sugeridas; cada um recebe argumentos (realm, cluster, intervalo de tempo) e orienta o modelo pelas ferramentas certas, na ordem correta.
| Prompt | O que faz |
|---|---|
audit_self_registration | Encontra todos os realms que ainda permitem autorregistro, em um cluster ou em todos |
review_upgrades | Identifica clusters com uma versão do Keycloak desatualizada e apresenta o caminho de atualização |
triage_failed_logins | Busca falhas de login recentes de um realm e as agrupa por IP de origem |
review_identity_providers | Lista as conexões SSO de um realm e verifica se uma específica está habilitada |
review_admin_changes | Mostra quem alterou o quê recentemente em um realm, com foco nas configurações de login e segurança |
provision_environment | Cria um cluster, adiciona um realm e configura um provedor de identidade, confirmando cada etapa |
set_up_custom_domain | Adiciona um domínio personalizado, retorna os registros DNS exatos, verifica e o direciona para um realm |
rotate_client_secret | Gera novamente o segredo do cliente de um aplicativo, detalhando primeiro o impacto potencial |
Os prompts seguem as mesmas restrições de acesso das ferramentas que mencionam: os três que fazem alterações só são oferecidos a sessões que poderiam chamar as ferramentas de escrita referenciadas, e suas instruções orientam o modelo a confirmar com você antes de alterar qualquer coisa. O requisito confirm=true para ferramentas destrutivas continua valendo.
Skills
Enquanto um prompt é um ponto de partida, uma skill é um manual operacional completo que o modelo carrega sob demanda. O servidor fornece quatro, por meio da extensão preliminar SEP-2640 Skills: ela declara io.modelcontextprotocol/skills em seus recursos, responde a skills/list e skills/get, e disponibiliza cada SKILL.md como um recurso comum em skill://<name>/SKILL.md, com um resumo sha256 em sua entrada de listagem. O diretório de plugins da OpenAI importa skills exatamente nesse formato.
| Skill | O que codifica |
|---|---|
auth-incident-triage | Triagem de “usuários não conseguem fazer login”: diferencia indisponibilidades da plataforma de ataques e alterações de configuração, usando eventos, logs do WAF e integridade do cluster. Somente leitura |
enterprise-sso-rollout | Configura um IdP empresarial em um realm de ponta a ponta: validação do emissor, registro do aplicativo upstream, configuração do broker, teste da conexão e verificação com eventos reais de login |
keycloak-migration-doctor | Verifica previamente uma exportação, importação ou migração do Keycloak em relação aos bloqueios que o suporte realmente encontra (políticas de script, o caminho legado /auth, expectativas de exportação parcial) e diagnostica uma tarefa com falha lendo seu error_message real, em vez do aviso genérico do painel |
keycloak-upgrade-readiness | Avalia a defasagem de versões, identifica o que a nova versão do Keycloak pode afetar (extensões, temas) e organiza a implantação entre ambientes usando uma exportação como plano de reversão |
As skills seguem as mesmas restrições de acesso das ferramentas que mencionam: os três fluxos de trabalho baseados em ferramentas de escrita não são disponibilizados para sessões somente leitura, e uma sessão com escopo limitado só recebe uma skill cujas ferramentas ela realmente pode usar. As fontes ficam em internal/tools/skills/, um diretório por skill, no formato padrão Agent Skills, para que também funcionem quando copiadas diretamente para um diretório local de skills.
Conexão
Para HTTP hospedado, o caminho mais simples é OAuth, que não exige nenhuma credencial:
claude mcp add --transport http skycloak https://mcp.skycloak.io
Na primeira chamada, seu navegador será aberto; você aprova na página de login do Skycloak e as ferramentas aparecem. Se você pertence a mais de um workspace, especifique qual deseja usar:
claude mcp add --transport http skycloak "https://mcp.skycloak.io?workspace=<workspace-id>"
Caso contrário, crie uma chave de API no painel do Skycloak e configure seu cliente MCP para enviá-la como token bearer:
claude mcp add --transport http skycloak https://mcp.skycloak.io --header "Authorization: Bearer sk_sc_XXX"
Isso adiciona o seguinte a .claude.json:
{
"mcpServers": {
"skycloak": {
"type": "http",
"url": "https://mcp.skycloak.io",
"headers": {
"Authorization": "Bearer sk_sc_XXX"
}
}
}
}
Gemini CLI instala o servidor hospedado como uma extensão, usando o manifesto deste repositório:
gemini extensions install https://github.com/sky-cloak/skycloak-mcp
Antigravity instala o servidor hospedado como um plugin, usando o pacote em plugins/skycloak/:
agy plugin install ./plugins/skycloak
Copilot CLI instala-o a partir do manifesto Agent Plugins na raiz do repositório, depois que a listagem for aprovada:
copilot plugin install skycloak@awesome-copilot
Para stdio local, entre uma vez e aponte seu cliente para 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 execução sem interface / CI (sem navegador), ignore init e passe a chave: adicione "env": { "SKYCLOAK_API_KEY": "sk_sc_..." } à configuração ou claude mcp add skycloak --env SKYCLOAK_API_KEY=sk_sc_... -- skycloak-mcp run --transport stdio.
Adicione --allow-writes somente quando pretender fazer alterações (entre com skycloak-mcp init --allow-writes ou use uma chave com escopo de escrita).
Adicione ?readonly=true a uma URL HTTP hospedada para expor somente ferramentas de leitura nessa sessão HTTP, ou ?readonly=false para solicitar a superfície de ferramentas com capacidade de escrita. O parâmetro de consulta usa false por padrão, mas as ferramentas de escrita só são registradas quando o servidor é iniciado com --allow-writes.
Adicione ?workspace=<uuid> para escolher o workspace em que uma sessão OAuth atuará. Isso só é necessário se você pertencer a mais de um; com um único workspace, o servidor o seleciona automaticamente e, se você pertencer a vários e não especificar nenhum, a conexão falha com uma mensagem que os lista.
Executar o transporte HTTP
skycloak-mcp run --transport http --http-addr :8080
Ele não precisa de credenciais próprias: os chamadores fornecem as suas em cada solicitação, portanto nada é injetado durante a implantação. GET /healthz e GET /readyz não exigem autenticação e informam apenas que o processo está ativo; intencionalmente, não verificam a API do Skycloak, para que uma interrupção upstream não faça as verificações de todas as réplicas falharem ao mesmo tempo. O servidor não mantém estado de sessão, portanto as réplicas não precisam de afinidade de sessão e podem ser escaladas ou reiniciadas livremente. SIGTERM interrompe novas conexões e conclui as chamadas em andamento.
O fluxo OAuth fica ativo sempre que SKYCLOAK_ISSUER e SKYCLOAK_DASHBOARD_URL estão definidos, como ocorre por padrão. Nesse caso, GET /.well-known/oauth-protected-resource é servido sem autenticação, identificando o realm como servidor de autorização. O valor de resource é obtido de SKYCLOAK_PUBLIC_URL quando definido; caso contrário, é derivado de Host e do esquema da própria solicitação, portanto uma implantação em um único host atrás de um ingress não precisa de configuração adicional. O esquema vem de X-Forwarded-Proto quando presente; caso contrário, usa https para qualquer host que não seja de loopback, pois o TLS termina upstream e publicar um identificador http:// não corresponderia à URL usada pelo cliente para se conectar. Defina SKYCLOAK_PUBLIC_URL se seu ingress reescrever Host. O documento também lista openid profile email como seu scopes_supported, e o desafio WWW-Authenticate os repete como um parâmetro scope, para que um cliente que leia qualquer um deles solicite esses valores ao realm: openid é obrigatório, pois a troca de token faz com que o painel chame o endpoint userinfo do Keycloak, e o Keycloak recusa um token concedido sem ele. Se um token chegar sem esse valor, a verificação o recusa com um 401 e o desafio, em vez de encaminhá-lo para uma troca que não pode ser concluída; assim, um cliente que ainda tenha uma concessão anterior para de tentar novamente e inicia uma nova sessão. Deixar em branco qualquer uma das variáveis do emissor ou do painel desativa completamente o OAuth, e o servidor volta a solicitar uma chave de API, sem oferecer outra opção.
OPENAI_APPS_CHALLENGE_TOKEN disponibiliza o token de verificação de domínio do diretório de plugins da OpenAI em /.well-known/openai-apps-challenge, somente como texto simples. Se não estiver definido, a rota não é registrada e o caminho retorna 404.
Na inicialização, uma linha de log informa a configuração resolvida (oauth=, issuer=, dashboard=, public_url=, endpoint=, allow_writes=), permitindo identificar uma implantação mal configurada sem precisar reimplantá-la. Cada solicitação recusada no fluxo OAuth gera uma linha de log que identifica a etapa que falhou (verify, exchange ou scopes), o status recebido pelo chamador e o erro subjacente. Uma falha de verificação inclui a validação que rejeitou o token (expired, wrong_issuer, bad_signature, unknown_key_id, wrong_token_type, no_openid_scope e assim por diante); uma falha de troca inclui o status do painel e o host chamado. Depois de verificado, o chamador é identificado pelo assunto do token, nunca por uma credencial: o token de acesso, o cabeçalho Authorization e a chave de API gerada nunca são registrados.
O que o servidor envia à API do Skycloak
O servidor hospedado e o binário local enviam os mesmos cabeçalhos à API do Skycloak (SKYCLOAK_ENDPOINT):
| Cabeçalho | Valor | Motivo |
|---|---|---|
API-Key | sua chave de API ou a chave gerada para a sessão | autentica a solicitação |
API-Version | SKYCLOAK_API_VERSION | fixa o contrato da API para o qual o servidor foi compilado |
User-Agent | skycloak-mcp/<version> | identifica o cliente |
X-MCP-Tool | o nome registrado da ferramenta, por exemplo skycloak_list_realms | informa qual ferramenta fez a solicitação |
X-MCP-Call-Id | um UUID aleatório gerado uma vez por chamada de ferramenta | agrupa todas as solicitações de uma chamada |
X-MCP-Tool e X-MCP-Call-Id são enviados somente em solicitações feitas durante o atendimento de uma chamada de ferramenta. Uma chamada pode fazer várias solicitações, uma por cluster quando cluster_id é omitido, e novamente quando 429 ou 5xx é repetido; todas compartilham o ID da chamada. O Skycloak usa esse par para contabilizar a frequência de uso de cada ferramenta, o que nos ajuda a decidir quais ferramentas melhorar, documentar ou descontinuar. Eles não contêm argumentos, resultados nem qualquer informação sobre você além do que a chave de API já identifica, e são enviados somente à API do Skycloak, nunca aos seus clusters Keycloak nem a qualquer outro lugar. Solicitações feitas fora de uma chamada de ferramenta, como entrar e gerar chaves de API, não os incluem.
Configuração
| Variável de ambiente | Padrão |
|---|---|
SKYCLOAK_API_KEY | nenhum (opcional para stdio; clientes HTTP fornecem cabeçalhos API-Key) |
SKYCLOAK_ENDPOINT | https://api.skycloak.io |
SKYCLOAK_API_VERSION | versão atual da API |
SKYCLOAK_ISSUER | https://login.app.skycloak.io/realms/skycloak (login da CLI e servidor de autorização usado pelo transporte HTTP para verificar tokens) |
SKYCLOAK_CLIENT_ID | skycloak-mcp (somente fluxo de dispositivo da CLI) |
SKYCLOAK_DASHBOARD_URL | https://app.skycloak.io (gera chaves da CLI e chaves de sessão HTTP) |
SKYCLOAK_PUBLIC_URL | nenhum (derivado de cada solicitação; defina-o quando o ingress reescrever Host) |
OPENAI_APPS_CHALLENGE_TOKEN | Disponibiliza o token de verificação do diretório de plugins da OpenAI em /.well-known/openai-apps-challenge. Se não estiver definido, esse caminho retorna 404. |
Comandos: init (login pelo navegador), run (iniciar o servidor), logout (remover a chave armazenada). init aceita --workspace <id>, --allow-writes, --allow-credentials e --ttl-days (padrão 90).
| Opção | Padrão | Descrição |
|---|---|---|
--transport | stdio | stdio ou http |
--http-addr | :8080 | endereço de escuta do transporte HTTP |
--allow-writes | false | habilita ferramentas que fazem alterações para stdio e permite que sessões HTTP com readonly=false registrem ferramentas de escrita |
Desenvolvimento
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
O cliente da API em internal/apiclient é gerado a partir da especificação OpenAPI do Skycloak
com oapi-codegen.
Mantendo a sincronização com a API
O cliente em internal/apiclient é gerado a partir de internal/apiclient/openapi.yaml com oapi-codegen; execute make generate para atualizá-lo. A CI falha se o código gerado e versionado divergir da especificação. As solicitações são repetidas em 429/5xx com backoff que leva Retry-After em conta.
Distribuição
Publicado como binários do GitHub e uma imagem de contêiner ghcr.io/sky-cloak/skycloak-mcp a cada tag, e disponibilizado no MCP Registry como io.skycloak/skycloak-mcp. A maioria das pessoas não precisa de nenhum dos dois: o servidor hospedado não requer instalação.
Pacotes de plugins
plugins/skycloak/ é uma pasta que atende a dois clientes: .antigravity-plugin/plugin.json com mcp_config.json para Antigravity, e .claude-plugin/plugin.json para Claude. Ambos apontam para o servidor hospedado e incluem as quatro skills, que são cópias idênticas, byte a byte, de internal/tools/skills/, pois o instalador recebe apenas essa pasta.
plugin.json e mcp.json, na raiz do repositório, são o manifesto Agent Plugins v1.0.0 lido pelo marketplace awesome-copilot do GitHub. Esse formato não permite um campo de logotipo, então o logotipo da listagem é informado em extensions["com.github.copilot"].
O campo version nesses manifestos e em .grok-plugin/plugin.json é definido pela CI a partir da tag de lançamento, pois as listagens do diretório acompanham main. A seção sobre atualizações do diretório do README do plugin explica isso.
Segurança
Relate vulnerabilidades de forma privada. Consulte SECURITY.md.
Colaboradores
Desenvolvido na Skycloak por Guilliano Molaire, Neville Omangi e Aphilas. O histórico do repositório foi consolidado quando ele foi aberto ao público, portanto o log de commits não reflete quem escreveu cada parte.
Licença
Apache-2.0. A descrição OpenAPI em internal/apiclient/openapi.yaml é gerada a partir da API da plataforma Skycloak e é © Skycloak; ela está incluída aqui para que o cliente possa ser gerado e verificado. Consulte NOTICE.