Skycloak

chính thức

Máy chủ Model Context Protocol cho Skycloak quản lý Keycloak. Quản lý cụm, realm, ứng dụng, SSO và người dùng từ bất kỳ máy khách MCP nào.

Bạn có thể làm gì với Skycloak MCP?

  • Kiểm kê và nâng cấp cụm — Liệt kê các cụm, kiểm tra phiên bản và xem lộ trình nâng cấp cho bất kỳ cụm nào đang chạy phiên bản cũ.
  • Quản lý realm và ứng dụng — Tạo hoặc cập nhật realm và ứng dụng, gán vai trò và xoay vòng bí mật ứng dụng của client.
  • Thiết lập nhà cung cấp danh tính — Thêm nhà cung cấp danh tính OIDC vào realm, kiểm tra kết nối và liệt kê các kết nối SSO hiện có.
  • Quản trị người dùng và nhóm — Liệt kê người dùng, vai trò và nhóm trong realm, sau đó gán vai trò hoặc thêm người dùng vào nhóm.
  • Kiểm tra nhật ký kiểm toán và sự kiện — Truy vấn sự kiện và nhật ký bảo mật, hoặc lấy các lần đăng nhập thất bại gần đây của một realm, được nhóm theo địa chỉ IP nguồn.
  • Đích SIEM và webhook — Tạo đích SIEM hoặc đăng ký webhook, rồi gửi sự kiện thử nghiệm để xác nhận việc gửi thành công.

Tài liệu

skycloak-mcp

Smithery

Máy chủ Model Context Protocol chính thức dành cho Skycloak (Keycloak được quản lý): quản lý cụm, realm, ứng dụng và SSO từ bất kỳ ứng dụng khách MCP nào (Claude Desktop, Claude Code, Cursor).

Trạng thái: bản phát hành sớm. Phạm vi công cụ đang được mở rộng; xem nhật ký thay đổi để biết những gì hiện có.

Bắt đầu nhanh

claude mcp add --transport http skycloak https://mcp.skycloak.io

Không cần khóa API, ID ứng dụng khách hay cấu hình. Trình duyệt của bạn sẽ mở ra, bạn đăng nhập vào Skycloak và các công cụ sẽ xuất hiện. Mọi ứng dụng khách MCP hỗ trợ HTTP có thể truyền luồng đều hoạt động theo cách tương tự: chỉ cần cung cấp URL, không cần gì khác.

Sau đó, hãy yêu cầu một việc:

  • "Những cụm Keycloak nào của tôi đang chậm cập nhật?"
  • "Tạo một realm staging trên cụm EU với đăng nhập bằng Google và GitHub."
  • "Ai đã được thêm vào realm production trong tuần qua?"
  • "Thiết lập một đích SIEM chuyển tiếp sự kiện quản trị đến webhook Datadog của chúng tôi."

Xác thực và an toàn

  • HTTP lưu trữ, dùng OAuth (không cần cấu hình thông tin xác thực). Trỏ ứng dụng khách của bạn đến https://mcp.skycloak.io mà không cần header. Máy chủ phản hồi 401 kèm đường dẫn đến siêu dữ liệu RFC 9728 tại /.well-known/oauth-protected-resource, ứng dụng khách thực hiện luồng mã ủy quyền qua trình duyệt với realm đăng nhập Skycloak, rồi mã truy cập nhận được sẽ được đổi lấy khóa API có thời hạn ngắn, giới hạn trong workspace mà phiên làm việc sử dụng. Khóa có hiệu lực trong một giờ và được tự động gia hạn. Không có gì được lưu trong cấu hình ứng dụng khách.
  • HTTP lưu trữ, dùng khóa API. Tạo khóa trong bảng điều khiển Skycloak và gửi khóa dưới dạng Authorization: Bearer <key> (hoặc API-Key: <key>). Mỗi yêu cầu mang thông tin xác thực riêng và chỉ hoạt động trong workspace của thông tin xác thực đó. Máy chủ không lưu trạng thái phiên, vì vậy yêu cầu không bao giờ kế thừa thông tin của người gọi khác. Khóa không được xác minh trước khi sử dụng: API Skycloak là nơi có thẩm quyền, nên khóa không hợp lệ sẽ hiển thị lỗi 401 ở lần gọi công cụ đầu tiên, thay vì lúc kết nối.
  • Công cụ phù hợp với vai trò của bạn. Khi dùng OAuth, danh sách công cụ được giới hạn theo phạm vi mà phiên làm việc cho phép, vì vậy thành viên workspace chỉ có quyền đọc sẽ không thấy các công cụ ghi có thể trả về 403. Khi dùng khóa API, toàn bộ công cụ đều được đăng ký vì máy chủ không thể biết phạm vi của khóa; lệnh gọi không được cấp quyền sẽ hiển thị lỗi 403 từ API.
  • stdio cục bộ. Chạy skycloak-mcp init và phê duyệt trong trình duyệt (luồng ủy quyền thiết bị OAuth 2.0). Lệnh này tạo khóa API giới hạn trong workspace, lưu khóa vào chuỗi khóa của hệ điều hành và tự động phát hiện workspace mặc định của bạn (truyền --workspace <id> để chọn workspace khác). skycloak-mcp logout xóa khóa đã lưu.
  • Không giao diện / CI. Đặt biến môi trường SKYCLOAK_API_KEY (tạo khóa trong bảng điều khiển Skycloak) để bỏ qua hoàn toàn trình duyệt. Biến này luôn được ưu tiên hơn chuỗi khóa.
  • Quyền ghi được kiểm soát bởi thông tin xác thực, không phải cờ. Máy chủ lưu trữ tại https://mcp.skycloak.io hỗ trợ ghi; những gì bạn thực sự có thể thay đổi phụ thuộc vào phạm vi của khóa và vai trò trong workspace: thành viên chỉ có quyền đọc không thể thay đổi bất cứ thứ gì, bất kể danh sách công cụ hiển thị ra sao. Thêm ?readonly=true vào URL để buộc phiên làm việc chỉ có các công cụ đọc. Ngược lại, tệp nhị phân cục bộ không đăng ký công cụ ghi trừ khi được khởi chạy với --allow-writes.
  • Thông tin xác thực cụm là tùy chọn. get_cluster_credentials trả về thông tin xác thực quản trị Keycloak của một cụm, mà trợ lý có khóa sau đó sẽ nhìn thấy; vì vậy, theo mặc định, init không yêu cầu phạm vi đó. Hãy dùng khóa có phạm vi này: tạo khóa trong bảng điều khiển hoặc đăng nhập qua stdio bằng skycloak-mcp init --allow-credentials. Nếu không có phạm vi này, công cụ trả về lỗi 403 giải thích cả hai cách.
  • Công cụ phá hủy yêu cầu xác nhận: chẳng hạn, xóa realm cần có đối số confirm=true rõ ràng.
  • Giới hạn tốc độ yêu cầu tùy theo gói Skycloak của bạn; khi nhận phản hồi 429, máy chủ sẽ hiển thị Retry-After.

Công cụ

Có 141 công cụ: 62 công cụ chỉ đọc và 79 công cụ ghi. Công cụ chỉ đọc luôn khả dụng. Trên máy chủ lưu trữ, các công cụ ghi cũng được đăng ký và được kiểm soát theo phạm vi của thông tin xác thực; tệp nhị phân cục bộ chỉ đăng ký chúng khi được khởi chạy với --allow-writes.

Tên công cụ có tiền tố skycloak_ mà bảng bên dưới lược bỏ, vì vậy list_clusters trong ứng dụng khách của bạn là skycloak_list_clusters.

Khu vựcChỉ đọcGhi (--allow-writes)
Cụmlist_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
Bảo mật biênget_cluster_security, list_cluster_captcha_domainsupdate_cluster_security, add_cluster_captcha_domain, remove_cluster_captcha_domain
Realmlist_realms, get_realmcreate_realm, update_realm, delete_realm
Ứng dụnglist_applications, get_application, list_application_roles, list_application_sessionscreate_application, update_application, delete_application, assign_application_role, remove_application_role, rotate_application_secret
Nhà cung cấp danh tínhlist_identity_providers, get_identity_provider, list_identity_provider_templates, discover_oidccreate_identity_provider (OIDC), update_identity_provider, delete_identity_provider, test_identity_provider
Người dùng, vai trò và nhómlist_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
Tên miền tùy chỉnhlist_domains, get_domain, list_domain_routes, get_domain_routecreate_domain, verify_domain, delete_domain, create_domain_route, update_domain_route, delete_domain_route
Thương hiệu và giao diệnlist_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
Phần mở rộnglist_extensions, list_cluster_extensionsinstall_extension, upgrade_extension, update_extension, uninstall_extension, delete_extension
SMTPget_smtpupsert_smtp, delete_smtp, test_smtp
Xuất và nhật kýlist_exports, get_export, get_logs, get_security_logs, query_eventscreate_export, delete_export, export_cluster_events
Nhập và xuất realmget_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
Webhooklist_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

Quy ước: các công cụ phá hủy (delete_*, uninstall_extension, cancel_cluster_upgrade, update_theme_content, update_theme_settings, restart_cluster_instances) yêu cầu confirm=true. update_theme_settings bật hoặc tắt exact_theme_names cho workspace; khóa API của người gọi phải được tạo cho chủ sở hữu hoặc quản trị viên workspace, nếu không sẽ nhận 403 ngay cả khi có themes:write. Khi bật tính năng này, các giao diện hiện có sẽ được chuyển sang tên được phân phối chính xác trong nền; giao diện có nội dung bị thay thế dưới tên chính xác của nó sẽ báo restart_required: true từ get_theme/list_themes/update_theme_content cho đến khi restart_cluster_instances khởi động lại các phiên bản Keycloak của cụm đó. Việc khởi động lại có thể được hoãn đến khung thời gian bảo trì của cụm thay vì áp dụng ngay, được báo cáo là deferred: true và, nếu biết, next_window. create_cluster chạy bất đồng bộ: thăm dò get_cluster cho đến khi cụm ở trạng thái available. create_domain trả về các bản ghi DNS mà khách hàng cần tạo; verify_domain kích hoạt kiểm tra DNS. set_theme_assignment kích hoạt giao diện tùy chỉnh theo từng loại giao diện Keycloak (chuỗi rỗng sẽ đặt lại về mặc định tích hợp sẵn). update_theme_content thay thế trực tiếp tệp lưu trữ của giao diện (ZIP mã hóa base64 hoặc JAR Keycloakify trong content_base64), đồng thời giữ nguyên ID, tên, realm và các phân công ứng dụng của giao diện, nhờ đó việc chỉnh sửa giao diện không còn đòi hỏi phải xóa rồi tải lên lại; thao tác này cần confirm=true vì không thể khôi phục tệp lưu trữ bị ghi đè, còn update_theme vẫn chỉ thay đổi tên, mô tả và phiên bản. Xem docs/theme-content-update.md để biết cách thực hiện lệnh gọi đó. update_cluster_security giữ nguyên các cài đặt CAPTCHA. Nhập/xuất realm di chuyển cấu hình của một realm và tách biệt với create_export, thao tác kết xuất toàn bộ cơ sở dữ liệu của một cụm: cả hai đều chạy bất đồng bộ, và tệp lưu trữ realm luôn được mã hóa, vì vậy cần mật khẩu đã dùng để xuất khi nhập lại. Có thể nhập realm trực tiếp từ bản xuất hiện có (source_export_id) hoặc từ tệp lưu trữ đã tải lên (create_realm_import_upload_url, PUT, rồi upload_s3_key); thao tác nhập tạo realm và từ chối tên bị trùng thay vì ghi đè, đồng thời cần confirm=true vì realm mang theo người dùng và thông tin xác thực.

Các phiên bản OpenFGA: mọi công cụ OpenFGA đều nhận cluster_id. create_openfga_instance liên kết một phiên bản OpenFGA với một realm của cụm; mỗi realm chỉ có tối đa một phiên bản. Lệnh này trả về 403 khi gói của workspace không bao gồm OpenFGA hoặc workspace đã đạt giới hạn số phiên bản, 409 khi realm đã có phiên bản, và 422 khi realm master, không tồn tại hoặc bị vô hiệu hóa. Thao tác chạy bất đồng bộ: thăm dò get_openfga_instance cho đến khi status ở trạng thái ready hoặc failed. Phiên bản chỉ chấp nhận token từ realm đó có chứa audience tương ứng; get_openfga_instance trả về api_url, issuer và audience để gọi phiên bản. Bộ ánh xạ audience đưa audience vào token của realm được thêm trong Keycloak. Có thể liệt kê và xóa mà không cần quyền truy cập OpenFGA. delete_openfga_instance xóa triển khai, tuyến và cơ sở dữ liệu; không thể khôi phục dữ liệu ủy quyền trong đó. Phiên bản hiển thị trạng thái deleting cho đến khi bị xóa hoàn toàn.

Vị trí cụm: location trong create_cluster, cũng như trong kết quả trả về của list_clusters, get_cluster và list_cluster_locations, là một trong các giá trị sau, không phân biệt chữ hoa chữ thường: us (US East), us-west (US West), ca (Canada), eu (Europe) hoặc au (Australia). us luôn có nghĩa là US East. Chỉ những workspace được cấp quyền mới có thể sử dụng us-west: list_cluster_locations liệt kê mọi vị trí có available được đặt cho workspace của bạn; tạo cụm ở vị trí bạn không thể sử dụng sẽ trả về lỗi API 400 "location not available".

Lời nhắc

Tám lời nhắc giúp bạn bắt đầu sử dụng các công cụ này. Ứng dụng khách hiển thị chúng dưới dạng lệnh gạch chéo hoặc hành động được đề xuất; mỗi lời nhắc nhận các đối số (realm, cụm, khoảng thời gian) và hướng dẫn mô hình gọi đúng công cụ theo đúng thứ tự.

PromptChức năng
audit_self_registrationTìm mọi realm vẫn cho phép tự đăng ký trên một hoặc tất cả các cụm
review_upgradesPhát hiện các cụm đang dùng phiên bản Keycloak cũ và vạch ra lộ trình nâng cấp
triage_failed_loginsLấy các lần đăng nhập thất bại gần đây của một realm và nhóm theo IP nguồn
review_identity_providersLiệt kê các kết nối SSO của một realm và kiểm tra xem một kết nối cụ thể có được bật hay không
review_admin_changesCho biết gần đây ai đã thay đổi gì trong một realm, tập trung vào cài đặt đăng nhập và bảo mật
provision_environmentTạo một cụm, thêm realm và kết nối nhà cung cấp danh tính, đồng thời xác nhận từng bước
set_up_custom_domainThêm miền tùy chỉnh, trả về chính xác các bản ghi DNS, xác minh rồi định tuyến miền đó đến một realm
rotate_client_secretTạo lại client secret của ứng dụng sau khi nêu rõ phạm vi ảnh hưởng

Các prompt được kiểm soát quyền truy cập giống như những công cụ mà chúng nhắc đến: ba prompt có thể thay đổi dữ liệu chỉ được cung cấp cho các phiên có thể gọi những công cụ ghi tương ứng, và hướng dẫn yêu cầu mô hình xác nhận với bạn trước khi thay đổi bất cứ điều gì. Yêu cầu confirm=true đối với các công cụ phá hủy vẫn được áp dụng bổ sung.

Kỹ năng

Nếu prompt là điểm khởi đầu thì kỹ năng là một cẩm nang vận hành đầy đủ mà mô hình tải theo yêu cầu. Máy chủ cung cấp bốn kỹ năng, thông qua tiện ích mở rộng SEP-2640 Skills ở trạng thái dự thảo: tiện ích này khai báo io.modelcontextprotocol/skills trong capabilities, phản hồi skills/list và skills/get, đồng thời cung cấp từng SKILL.md dưới dạng tài nguyên thông thường tại skill://<name>/SKILL.md, kèm theo mã băm sha256 trong mục liệt kê. Thư mục plugin của OpenAI nhập các kỹ năng theo đúng định dạng này.

Kỹ năngNội dung
auth-incident-triagePhân loại sự cố “người dùng không thể đăng nhập”: phân biệt sự cố nền tảng với tấn công và thay đổi cấu hình bằng cách sử dụng sự kiện, nhật ký WAF và tình trạng cụm. Chỉ đọc
enterprise-sso-rolloutKết nối IdP doanh nghiệp với một realm từ đầu đến cuối: xác thực issuer, đăng ký ứng dụng upstream, cấu hình broker, kiểm tra kết nối và xác minh bằng các sự kiện đăng nhập thực tế
keycloak-migration-doctorKiểm tra trước một bản xuất, nhập hoặc di chuyển Keycloak dựa trên các vấn đề mà bộ phận hỗ trợ thường gặp (chính sách script, đường dẫn /auth cũ, kỳ vọng về bản xuất một phần), đồng thời chẩn đoán tác vụ thất bại bằng cách đọc error_message thực tế thay vì thông báo chung trên bảng điều khiển
keycloak-upgrade-readinessĐánh giá độ lệch phiên bản, xác định những gì phiên bản Keycloak mới làm hỏng (phần mở rộng, giao diện) và sắp xếp thứ tự triển khai trên các môi trường, dùng bản xuất làm phương án khôi phục

Kỹ năng được kiểm soát quyền truy cập giống như các công cụ mà chúng nhắc đến: ba quy trình dựa trên công cụ ghi không được cung cấp cho các phiên chỉ đọc, và một phiên có phạm vi giới hạn chỉ được cung cấp kỹ năng sử dụng những công cụ mà phiên đó thực sự có quyền truy cập. Mã nguồn nằm trong internal/tools/skills/, mỗi kỹ năng có một thư mục riêng theo định dạng Agent Skills tiêu chuẩn, nên cũng có thể sao chép trực tiếp vào thư mục kỹ năng cục bộ.

Kết nối

Với HTTP được lưu trữ, cách đơn giản nhất là dùng OAuth, không cần thông tin xác thực:

claude mcp add --transport http skycloak https://mcp.skycloak.io

Lần gọi đầu tiên sẽ mở trình duyệt; bạn phê duyệt trên trang đăng nhập Skycloak, rồi các công cụ sẽ xuất hiện. Nếu bạn thuộc nhiều workspace, hãy chỉ định workspace muốn dùng:

claude mcp add --transport http skycloak "https://mcp.skycloak.io?workspace=<workspace-id>"

Nếu không, hãy tạo API key trong bảng điều khiển Skycloak và cấu hình MCP client gửi key đó dưới dạng bearer token:

claude mcp add --transport http skycloak https://mcp.skycloak.io --header "Authorization: Bearer sk_sc_XXX"

Thao tác này thêm nội dung sau vào .claude.json:

{
  "mcpServers": {
    "skycloak": {
      "type": "http",
      "url": "https://mcp.skycloak.io",
      "headers": {
        "Authorization": "Bearer sk_sc_XXX"
      }
    }
  }
}

Gemini CLI cài đặt máy chủ được lưu trữ dưới dạng tiện ích mở rộng, từ manifest trong kho lưu trữ này:

gemini extensions install https://github.com/sky-cloak/skycloak-mcp

Antigravity cài đặt máy chủ được lưu trữ dưới dạng plugin, từ gói trong plugins/skycloak/:

agy plugin install ./plugins/skycloak

Copilot CLI cài đặt máy chủ từ manifest Agent Plugins ở thư mục gốc của kho lưu trữ sau khi mục liệt kê được phê duyệt:

copilot plugin install skycloak@awesome-copilot

Với stdio cục bộ, hãy đăng nhập một lần, sau đó trỏ client đến skycloak-mcp run:

skycloak-mcp init        # one-time browser sign-in; stores a key in your keychain

Claude Desktop / Cursor (cục bộ, stdio):

{
  "mcpServers": {
    "skycloak": {
      "command": "skycloak-mcp",
      "args": ["run", "--transport", "stdio"]
    }
  }
}

Claude Code:

claude mcp add skycloak -- skycloak-mcp run --transport stdio

Với môi trường không có giao diện / CI (không có trình duyệt), bỏ qua init và thay vào đó truyền key: thêm "env": { "SKYCLOAK_API_KEY": "sk_sc_..." } vào cấu hình hoặc claude mcp add skycloak --env SKYCLOAK_API_KEY=sk_sc_... -- skycloak-mcp run --transport stdio.

Chỉ thêm --allow-writes khi bạn định thực hiện thay đổi (đăng nhập bằng skycloak-mcp init --allow-writes hoặc dùng key có phạm vi ghi).

Thêm ?readonly=true vào URL HTTP được lưu trữ để chỉ cung cấp các công cụ chỉ đọc cho phiên HTTP đó, hoặc ?readonly=false để yêu cầu tập công cụ có quyền ghi. Tham số truy vấn mặc định là false, nhưng công cụ ghi chỉ được đăng ký khi máy chủ được khởi chạy với --allow-writes.

Thêm ?workspace=<uuid> để chọn workspace mà phiên OAuth sẽ hoạt động. Chỉ cần thiết khi bạn thuộc nhiều workspace; nếu chỉ có một workspace, máy chủ sẽ tự chọn. Nếu bạn thuộc nhiều workspace nhưng không chỉ định workspace nào, kết nối sẽ thất bại và hiển thị thông báo liệt kê các workspace đó.

Chạy giao thức truyền tải HTTP

skycloak-mcp run --transport http --http-addr :8080

Bản thân máy chủ không cần thông tin xác thực: bên gọi cung cấp thông tin xác thực trong từng yêu cầu, vì vậy không cần chèn gì khi triển khai. GET /healthz và GET /readyz không yêu cầu xác thực và chỉ báo rằng tiến trình đang hoạt động; chúng cố ý không kiểm tra Skycloak API, để sự cố thoáng qua ở upstream không khiến mọi bản sao cùng lúc bị đánh dấu là không hoạt động. Máy chủ không lưu trạng thái phiên, vì vậy các bản sao không cần tính năng duy trì phiên và có thể được mở rộng hoặc khởi động lại tùy ý. SIGTERM ngừng nhận kết nối mới và xử lý hết các lệnh gọi đang chạy.

Luồng OAuth luôn được bật khi SKYCLOAK_ISSUER và SKYCLOAK_DASHBOARD_URL được đặt, đây là thiết lập mặc định. Khi đó, GET /.well-known/oauth-protected-resource được cung cấp mà không cần xác thực và chỉ định realm làm máy chủ ủy quyền. Giá trị resource được lấy từ SKYCLOAK_PUBLIC_URL nếu được đặt; nếu không, giá trị này được lấy từ Host và giao thức của chính yêu cầu. Vì vậy, triển khai trên một máy chủ duy nhất phía sau ingress không cần cấu hình bổ sung. Giao thức được lấy từ X-Forwarded-Proto nếu có; nếu không, mặc định là https đối với mọi máy chủ không phải loopback, vì TLS kết thúc ở upstream và việc công bố mã định danh http:// sẽ không khớp với URL mà client đã kết nối. Hãy đặt SKYCLOAK_PUBLIC_URL nếu ingress của bạn viết lại Host. Tài liệu cũng liệt kê openid profile email làm scopes_supported, và thử thách WWW-Authenticate lặp lại chúng dưới dạng tham số scope, nên client đọc một trong hai sẽ yêu cầu realm cấp chúng: openid là bắt buộc, vì quá trình trao đổi token khiến bảng điều khiển gọi endpoint userinfo của Keycloak và Keycloak từ chối token được cấp mà không có quyền này. Token đến mà thiếu quyền này sẽ bị từ chối ở bước xác minh kèm theo 401 và thử thách, thay vì được chuyển tiếp đến một quá trình trao đổi chắc chắn thất bại. Nhờ vậy, client vẫn giữ quyền cấp từ trước sẽ ngừng thử lại và đăng nhập lại. Nếu xóa giá trị của biến issuer hoặc biến bảng điều khiển, OAuth sẽ bị tắt hoàn toàn và máy chủ sẽ quay lại chỉ yêu cầu API key.

OPENAI_APPS_CHALLENGE_TOKEN cung cấp token xác minh miền của thư mục plugin OpenAI tại /.well-known/openai-apps-challenge, dưới dạng văn bản thuần và không có nội dung nào khác. Nếu không được đặt, route sẽ không được đăng ký và đường dẫn sẽ trả về 404.

Khi khởi động, máy chủ ghi một dòng nhật ký về cấu hình đã xác định (oauth=, issuer=, dashboard=, public_url=, endpoint=, allow_writes=), giúp phát hiện triển khai cấu hình sai mà không cần triển khai lại. Mỗi yêu cầu bị từ chối trên luồng OAuth sẽ ghi một dòng nhật ký nêu giai đoạn thất bại (verify, exchange hoặc scopes), mã trạng thái mà bên gọi nhận được và lỗi gốc. Lỗi xác minh bổ sung bước kiểm tra đã từ chối token (expired, wrong_issuer, bad_signature, unknown_key_id, wrong_token_type, no_openid_scope, v.v.); lỗi trao đổi bổ sung trạng thái của bảng điều khiển và máy chủ được gọi. Sau khi xác minh, bên gọi được nhận diện bằng subject của token, không bao giờ bằng thông tin xác thực: access token, header Authorization và API key được tạo ra không bao giờ được ghi vào nhật ký.

Nội dung máy chủ gửi đến Skycloak API

Máy chủ được lưu trữ và binary cục bộ gửi cùng các header đến Skycloak API (SKYCLOAK_ENDPOINT):

HeaderGiá trịLý do
API-KeyAPI key của bạn hoặc key được tạo cho phiênxác thực yêu cầu
API-VersionSKYCLOAK_API_VERSIONcố định hợp đồng API mà máy chủ được xây dựng dựa trên
User-Agentskycloak-mcp/<version>nhận diện client
X-MCP-Tooltên đã đăng ký của công cụ, ví dụ skycloak_list_realmscho biết công cụ nào đã thực hiện yêu cầu
X-MCP-Call-IdUUID ngẫu nhiên được tạo một lần cho mỗi lần gọi công cụnhóm mọi yêu cầu thuộc cùng một lần gọi

X-MCP-Tool và X-MCP-Call-Id chỉ được gửi trong các yêu cầu phát sinh khi xử lý một lần gọi công cụ. Một lần gọi có thể tạo ra nhiều yêu cầu: mỗi cụm một yêu cầu khi bỏ qua cluster_id, và thêm yêu cầu khi thử lại 429 hoặc 5xx; tất cả đều dùng chung ID của lần gọi đó. Skycloak dùng cặp này để đếm tần suất sử dụng từng công cụ, qua đó giúp chúng tôi biết nên cải thiện, viết tài liệu hay ngừng cung cấp công cụ nào. Chúng không chứa đối số, kết quả hay thông tin nào về bạn ngoài những gì API key đã nhận diện, và chỉ được gửi đến Skycloak API, không bao giờ đến các cụm Keycloak của bạn hay bất kỳ nơi nào khác. Các yêu cầu phát sinh ngoài một lần gọi công cụ, chẳng hạn như đăng nhập và tạo API key, không gửi hai header này.

Cấu hình

Biến môi trườngMặc định
SKYCLOAK_API_KEYkhông có (tùy chọn với stdio; client HTTP thay vào đó cung cấp header API-Key)
SKYCLOAK_ENDPOINThttps://api.skycloak.io
SKYCLOAK_API_VERSIONphiên bản API hiện tại
SKYCLOAK_ISSUERhttps://login.app.skycloak.io/realms/skycloak (đăng nhập CLI và máy chủ ủy quyền mà giao thức truyền tải HTTP dùng để xác minh token)
SKYCLOAK_CLIENT_IDskycloak-mcp (chỉ luồng thiết bị CLI)
SKYCLOAK_DASHBOARD_URLhttps://app.skycloak.io (tạo key cho CLI và phiên HTTP)
SKYCLOAK_PUBLIC_URLkhông có (được suy ra từ từng yêu cầu; hãy đặt biến này khi ingress viết lại Host)
OPENAI_APPS_CHALLENGE_TOKENCung cấp token xác minh của thư mục plugin OpenAI tại /.well-known/openai-apps-challenge. Nếu không được đặt, đường dẫn đó sẽ trả về 404.

Lệnh: init (đăng nhập bằng trình duyệt), run (chạy máy chủ), logout (xóa key đã lưu). init chấp nhận --workspace <id>, --allow-writes, --allow-credentials và --ttl-days (mặc định là 90).

CờMặc địnhMô tả
--transportstdiostdio hoặc http
--http-addr:8080địa chỉ lắng nghe của giao thức truyền tải HTTP
--allow-writesfalsebật công cụ có thể thay đổi dữ liệu cho stdio và cho phép các phiên HTTP có readonly=false đăng ký công cụ ghi

Phát triển

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

Client API trong internal/apiclient được tạo từ đặc tả OpenAPI của Skycloak bằng oapi-codegen.

Đồng bộ với API

Client trong internal/apiclient được tạo từ internal/apiclient/openapi.yaml bằng oapi-codegen; chạy make generate để cập nhật. CI sẽ thất bại nếu mã được tạo đã commit không còn khớp với đặc tả. Các yêu cầu được thử lại khi gặp 429/5xx với cơ chế chờ lùi có xét đến Retry-After.

Phân phối

Được phát hành dưới dạng binary GitHub và ảnh container ghcr.io/sky-cloak/skycloak-mcp cho mỗi tag, đồng thời được xuất bản lên MCP Registry với tên io.skycloak/skycloak-mcp. Hầu hết mọi người không cần dùng cả hai: máy chủ được lưu trữ không cần cài đặt.

Gói plugin

plugins/skycloak/ là một thư mục dùng cho hai client: .antigravity-plugin/plugin.json với mcp_config.json cho Antigravity, và .claude-plugin/plugin.json cho Claude. Cả hai đều trỏ đến máy chủ được lưu trữ và đi kèm bốn kỹ năng, là các bản sao giống hệt từng byte của internal/tools/skills/ vì trình cài đặt chỉ nhận thư mục đó. plugin.json và mcp.json ở thư mục gốc của kho lưu trữ là tệp kê khai Agent Plugins v1.0.0 mà marketplace awesome-copilot của GitHub đọc. Định dạng đó không cho phép có trường logo, vì vậy logo của danh sách được đặt trong extensions["com.github.copilot"].

Trường version trong các tệp kê khai đó và trong .grok-plugin/plugin.json được CI thiết lập dựa trên thẻ phát hành, vì các danh sách thư mục theo dõi main. Phần cập nhật thư mục trong README của plugin mô tả nội dung này.

Bảo mật

Vui lòng báo cáo riêng tư các lỗ hổng bảo mật. Xem SECURITY.md.

Người đóng góp

Được xây dựng tại Skycloak bởi Guilliano Molaire, Neville Omangi và Aphilas. Lịch sử kho lưu trữ đã được gộp lại khi kho được công khai, vì vậy nhật ký commit không phản ánh ai đã viết phần nào.

Giấy phép

Apache-2.0. Mô tả OpenAPI trong internal/apiclient/openapi.yaml được tạo từ API nền tảng Skycloak và thuộc bản quyền của Skycloak; tệp được đưa vào đây để có thể tạo và xác minh client. Xem NOTICE.