Skycloak

skycloak-mcp

เซิร์ฟเวอร์ Model Context Protocol อย่างเป็นทางการสำหรับ Skycloak (Keycloak ที่มีการจัดการ): จัดการคลัสเตอร์, realm, แอปพลิเคชัน และ SSO ของคุณจากไคลเอนต์ MCP ใดก็ได้ (Claude Desktop, Claude Code, Cursor)

สถานะ: รุ่นแรกเริ่ม ครอบคลุมเครื่องมือกำลังเพิ่มขึ้นเรื่อยๆ ดู changelog สำหรับสิ่งที่พร้อมใช้งาน

เริ่มต้นอย่างรวดเร็ว

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

ไม่ต้องใช้ API key, ไม่ต้องใช้ client ID, ไม่ต้องกำหนดค่าอะไร เบราว์เซอร์ของคุณจะเปิดขึ้น คุณลงชื่อเข้าใช้ Skycloak และเครื่องมือต่างๆ จะปรากฏขึ้น ไคลเอนต์ MCP ใดก็ตามที่รองรับ streamable HTTP ทำงานในลักษณะเดียวกัน: ให้ URL แค่นั้น

จากนั้นขออะไรก็ได้:

• "คลัสเตอร์ Keycloak ของฉันตัวไหนที่ตามหลังเรื่องอัปเกรดอยู่?"
• "สร้าง staging realm บนคลัสเตอร์ EU พร้อมการลงชื่อเข้าด้วย Google และ GitHub"
• "ใครถูกเพิ่มเข้าไปใน production realm ในสัปดาห์ที่ผ่านมา?"
• "ตั้งค่า SIEM destination ที่ส่งต่อ admin events ไปยัง Datadog webhook ของเรา"

การรับรองความถูกต้องและความปลอดภัย

• **โฮสต์ HTTP พร้อม OAuth (ไม่ต้องกำหนดค่า credential) ชี้ไคลเอนต์ของคุณไปที่ https://mcp.skycloak.io โดยไม่ต้องมี header เซิร์ฟเวอร์ตอบกลับ 401 พร้อมตัวชี้ไปยัง metadata ตาม RFC 9728 ที่ /.well-known/oauth-protected-resource ไคลเอนต์จะรัน browser authorization-code flow กับ Skycloak login realm และ access token ที่ได้รับจะถูกแลกเป็น API key ระยะสั้นที่จำกัดขอบเขตตาม workspace ซึ่งเซสชันจะใช้ดำเนินการ key มีอายุหนึ่งชั่วโมงและต่ออายุอัตโนมัติ ไม่มีอะไรถูกเก็บในการกำหนดค่าไคลเอนต์ของคุณ
• โฮสต์ HTTP พร้อม API key สร้าง key ใน แดชบอร์ด Skycloak และส่งเป็น Authorization: Bearer <key> (หรือ API-Key: <key>) ทุกคำขอมี credential ของตัวเองและดำเนินการเฉพาะใน workspace ของ credential นั้นเท่านั้น เซิร์ฟเวอร์ไม่เก็บสถานะเซสชัน ดังนั้นคำขอหนึ่งจะไม่สืบทอดสิทธิ์ของผู้เรียกอื่น key จะไม่ถูกตรวจสอบก่อนใช้งาน: Skycloak API เป็นผู้ตัดสิน ดังนั้น key ที่ไม่ถูกต้องจะแสดงเป็น 401 ในการเรียกเครื่องมือครั้งแรกแทนที่จะเป็นตอนเชื่อมต่อ
• เครื่องมือตรงกับบทบาทของคุณ ผ่าน OAuth รายการเครื่องมือจะถูกตัดให้เหลือเท่าที่ scope ของเซสชันอนุญาต ดังนั้นสมาชิก workspace แบบอ่านอย่างเดียวจะไม่เห็นเครื่องมือเขียนที่อาจตอบ 403 ด้วย API key พื้นผิวทั้งหมดจะถูกลงทะเบียน เนื่องจาก scope ของ key ไม่สามารถมองเห็นได้จากเซิร์ฟเวอร์ และการเรียกที่ไม่ได้รับอนุญาตจะแสดงเป็น 403 จาก API
• Local stdio รัน skycloak-mcp init และอนุมัติในเบราว์เซอร์ของคุณ (OAuth 2.0 device authorization flow) มันจะสร้าง API key ที่จำกัดขอบเขตตาม workspace เก็บไว้ใน keychain ของระบบปฏิบัติการ และตรวจจับ workspace เริ่มต้นของคุณโดยอัตโนมัติ (ส่ง --workspace <id> เพื่อเลือกอื่น) skycloak-mcp logout ลบ key ที่เก็บไว้
• Headless / CI ตั้งค่าตัวแปรสภาพแวดล้อม SKYCLOAK_API_KEY (สร้าง key ใน แดชบอร์ด Skycloak) เพื่อข้ามเบราว์เซอร์ทั้งหมด มันจะมีความสำคัญเหนือกว่า keychain เสมอ
• การเขียนถูกจำกัดด้วย credential ของคุณ ไม่ใช่ด้วย flag เซิร์ฟเวอร์ที่โฮสต์ที่ https://mcp.skycloak.io รันแบบรองรับการเขียน และสิ่งที่คุณเปลี่ยนแปลงได้จริงถูกจำกัดด้วย scope ของ key และบทบาท workspace ของคุณ: สมาชิกแบบอ่านอย่างเดียวไม่สามารถเปลี่ยนแปลงอะไรได้ ไม่ว่ารายการเครื่องมือจะพูดว่าอย่างไร เพิ่ม ?readonly=true ลงใน URL เพื่อบังคับพื้นผิวเครื่องมือแบบอ่านอย่างเดียวสำหรับเซสชัน ไบนารีในเครื่องเป็นไปในทางตรงกันข้ามและไม่ลงทะเบียนเครื่องมือเขียนใดๆ เว้นแต่จะเริ่มด้วย --allow-writes
• Cluster credentials เป็นแบบเลือกใช้ get_cluster_credentials ส่งคืนข้อมูลประจำตัวผู้ดูแลระบบ Keycloak ของคลัสเตอร์ ซึ่งผู้ช่วยที่ถือ key จะเห็นได้ ดังนั้น init จึงไม่ขอ scope นั้นโดยค่าเริ่มต้น ใช้ key ที่มี scope นั้น: สร้างในแดชบอร์ด หรือผ่าน stdio ลงชื่อเข้าด้วย skycloak-mcp init --allow-credentials หากไม่มี เครื่องมือจะส่งคืน 403 ที่อธิบายทั้งสองเส้นทาง
• เครื่องมือที่ทำลายล้างต้องมีการยืนยัน: การลบ realm เช่น ต้องมีอาร์กิวเมนต์ confirm=true อย่างชัดเจน
• คำขอถูกจำกัดอัตราตามแผน Skycloak ของคุณ; ในการตอบสนอง 429 เซิร์ฟเวอร์จะแสดง Retry-After

เครื่องมือ

137 เครื่องมือ: 60 แบบอ่านอย่างเดียวและ 77 แบบเขียน เครื่องมืออ่านอย่างเดียวพร้อมใช้งานเสมอ บนเซิร์ฟเวอร์ที่โฮสต์ เครื่องมือเขียนถูกลงทะเบียนด้วยและถูกจำกัดด้วย scope ของ credential ของคุณ; ไบนารีในเครื่องลงทะเบียนเฉพาะเมื่อเริ่มด้วย --allow-writes

ชื่อเครื่องมือมีคำนำหน้า skycloak_ ซึ่งตารางด้านล่างละไว้ ดังนั้น list_clusters คือ skycloak_list_clusters ในไคลเอนต์ของคุณ

พื้นที่	อ่านอย่างเดียว	เขียน (--allow-writes)
คลัสเตอร์	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
ความปลอดภัยขอบเขต	get_cluster_security, list_cluster_captcha_domains	update_cluster_security, add_cluster_captcha_domain, remove_cluster_captcha_domain
Realm	list_realms, get_realm	create_realm, update_realm, delete_realm
แอปพลิเคชัน	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
ผู้ให้บริการระบุตัวตน	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
ผู้ใช้, บทบาทและกลุ่ม	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
โดเมนที่กำหนดเอง	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
แบรนด์และธีม	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
ส่วนขยาย	list_extensions, list_cluster_extensions	install_extension, upgrade_extension, update_extension, uninstall_extension, delete_extension
SMTP	get_smtp	upsert_smtp, delete_smtp, test_smtp
การส่งออกและบันทึก	list_exports, get_export, get_logs, get_security_logs, query_events	create_export, delete_export, export_cluster_events
การนำเข้าและส่งออก Realm	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

ข้อตกลง: เครื่องมือที่ทำลายล้าง (delete_*, uninstall_extension, cancel_cluster_upgrade, update_theme_content, update_theme_settings, restart_cluster_instances) ต้องมี confirm=true update_theme_settings เปิดหรือปิด exact_theme_names สำหรับ workspace; API key ของผู้เรียกต้องถูกสร้างสำหรับเจ้าของหรือผู้ดูแล workspace มิฉะนั้นจะได้รับ 403 แม้จะมี themes:write การเปิดใช้งานจะย้ายธีมที่มีอยู่ไปยังชื่อที่ให้บริการจริงในเบื้องหลัง; ธีมที่เนื้อหาถูกแทนที่ภายใต้ชื่อจริงจะรายงาน restart_required: true จาก get_theme/list_themes/update_theme_content จนกว่า restart_cluster_instances จะรีสตาร์ทอินสแตนซ์ Keycloak ของคลัสเตอร์นั้น การรีสตาร์ทอาจถูกเลื่อนไปยังช่วงเวลาบำรุงรักษาของคลัสเตอร์แทนที่จะใช้ทันที รายงานเป็น deferred: true และเมื่อทราบ next_window create_cluster เป็นแบบอะซิงโครนัส: โพล get_cluster จนกว่าคลัสเตอร์จะเป็น available create_domain ส่งคืนระเบียน DNS ที่ลูกค้าต้องสร้าง; verify_domain เรียกใช้การตรวจสอบ DNS set_theme_assignment เปิดใช้งานธีมที่กำหนดเองตามประเภทธีม Keycloak (สตริงว่างรีเซ็ตเป็นค่าเริ่มต้นในตัว) update_theme_content แทนที่ไฟล์เก็บถาวรของธีมในตำแหน่งเดิม (base64 ZIP หรือ Keycloakify JAR ใน content_base64) โดยคง ID, ชื่อ และการกำหนด realm และแอปพลิเคชันของธีมไว้ ดังนั้นการแก้ไขธีมจึงไม่หมายถึงการลบและอัปโหลดใหม่; ต้องใช้ confirm=true เพราะไฟล์เก็บถาวรที่ถูกเขียนทับไม่สามารถกู้คืนได้ และ update_theme ยังคงเปลี่ยนเฉพาะชื่อ คำอธิบาย และเวอร์ชัน ดู docs/theme-content-update.md สำหรับวิธีเรียกใช้ update_cluster_security ไม่แตะต้องการตั้งค่า CAPTCHA การนำเข้า/ส่งออก realm ย้ายการกำหนดค่าของ realm หนึ่งและแยกจาก create_export ซึ่งถ่ายโอนฐานข้อมูลทั้งคลัสเตอร์: ทั้งสองเป็นแบบอะซิงโครนัส และไฟล์เก็บถาวร realm ถูกเข้ารหัสเสมอ ดังนั้นรหัสผ่านที่ใช้ส่งออกจึงจำเป็นต้องนำเข้าอีกครั้ง realm สามารถนำเข้าจากการส่งออกที่มีอยู่ได้โดยตรง (source_export_id) หรือจากไฟล์เก็บถาวรที่อัปโหลด (create_realm_import_upload_url, PUT, จากนั้น upload_s3_key); การนำเข้าสร้าง realm และปฏิเสธการชนของชื่อแทนที่จะเขียนทับ และต้องใช้ confirm=true เพราะนำผู้ใช้และข้อมูลประจำตัวมาด้วย

พรอมต์

พรอมต์แปดรายการให้จุดเริ่มต้นสู่พื้นผิวเครื่องมือนั้น ไคลเอนต์แสดงเป็นคำสั่งเครื่องหมายทับหรือการกระทำที่แนะนำ; แต่ละรายการรับอาร์กิวเมนต์ (realm, คลัสเตอร์, ช่วงเวลา) และนำโมเดลผ่านเครื่องมือที่ถูกต้องตามลำดับที่ถูกต้อง

พรอมต์	สิ่งที่ทำ
audit_self_registration	ค้นหาทุก realm ที่ยังอนุญาตการลงทะเบียนด้วยตนเอง ข้ามคลัสเตอร์หนึ่งหรือทั้งหมด
review_upgrades	ระบุคลัสเตอร์ที่ตามหลังเวอร์ชัน Keycloak และวางแผนเส้นทางการอัปเกรด
triage_failed_logins	ดึงการเข้าสู่ระบบที่ล้มเหลวล่าสุดสำหรับ realm และจัดกลุ่มตาม IP ต้นทาง
review_identity_providers	แสดงรายการการเชื่อมต่อ SSO ของ realm และตรวจสอบว่าการเชื่อมต่อเฉพาะเปิดใช้งานหรือไม่
review_admin_changes	แสดงว่าใครเปลี่ยนแปลงอะไรใน realm เมื่อเร็วๆ นี้ เน้นการตั้งค่าการเข้าสู่ระบบและความปลอดภัย
provision_environment	สร้างคลัสเตอร์ เพิ่ม realm และเชื่อมต่อผู้ให้บริการระบุตัวตน ยืนยันแต่ละขั้นตอน
set_up_custom_domain	เพิ่มโดเมนที่กำหนดเอง ส่งคืนระเบียน DNS ที่แน่นอน ตรวจสอบ และกำหนดเส้นทางไปยัง realm
rotate_client_secret	สร้าง client secret ของแอปพลิเคชันใหม่พร้อมระบุขอบเขตผลกระทบก่อน

พรอมต์ถูกจำกัดเช่นเดียวกับเครื่องมือที่อ้างถึง: สามรายการที่เปลี่ยนแปลงจะเสนอเฉพาะเซสชันที่สามารถเรียกเครื่องมือเขียนที่อ้างถึง และคำแนะนำบอกให้โมเดลยืนยันกับคุณก่อนเปลี่ยนแปลงอะไรก็ตาม ข้อกำหนด confirm=true สำหรับเครื่องมือที่ทำลายล้างยังคงใช้เพิ่มเติม

ทักษะ

ในขณะที่พรอมต์เป็นจุดเริ่มต้น ทักษะคือคู่มือปฏิบัติการฉบับเต็มที่โมเดลโหลดตามความต้องการ เซิร์ฟเวอร์มาพร้อมสี่ทักษะ ให้บริการผ่านส่วนขยาย SEP-2640 Skills ฉบับร่าง: ประกาศ io.modelcontextprotocol/skills ในความสามารถ ตอบ skills/list และ skills/get และให้บริการแต่ละ SKILL.md เป็นทรัพยากรธรรมดาที่ skill://<name>/SKILL.md พร้อม sha256 digest ในรายการ ไดเรกทอรีปลั๊กอินของ OpenAI นำเข้าทักษะในรูปแบบนี้พอดี

ทักษะ	สิ่งที่เข้ารหัส
auth-incident-triage	คัดแยก "ผู้ใช้ไม่สามารถเข้าสู่ระบบ": แยกการหยุดทำงานของแพลตฟอร์มจากการโจมตีและการเปลี่ยนแปลงการกำหนดค่า โดยใช้เหตุการณ์ บันทึก WAF และสถานะคลัสเตอร์ อ่านอย่างเดียว
enterprise-sso-rollout	เชื่อมต่อ IdP ระดับองค์กรเข้ากับ realm แบบครบวงจร: การตรวจสอบ issuer, การลงทะเบียนแอปต้นทาง, การกำหนดค่า broker, การทดสอบการเชื่อมต่อ และการตรวจสอบกับเหตุการณ์การเข้าสู่ระบบจริง
keycloak-migration-doctor	ตรวจสอบล่วงหน้าการส่งออก นำเข้า หรือย้ายข้อมูล Keycloak กับอุปสรรคที่ฝ่ายสนับสนุนพบจริง (นโยบายสคริปต์, เส้นทาง /auth แบบเดิม, ความคาดหวังการส่งออกบางส่วน) และวินิจฉัยงานที่ล้มเหลวโดยอ่าน error_message จริงแทนการแจ้งเตือนแดชบอร์ดทั่วไป
keycloak-upgrade-readiness	ประเมินความคลาดเคลื่อนของเวอร์ชัน หาว่า Keycloak เวอร์ชันใหม่ทำลายอะไร (ส่วนขยาย, ธีม) และจัดลำดับการเผยแพร่ข้ามสภาพแวดล้อมโดยใช้การส่งออกเป็นแผนการย้อนกลับ

ทักษะใช้การควบคุมการเข้าถึงเดียวกันกับเครื่องมือที่อ้างถึง: เวิร์กโฟลว์สามรายการที่สร้างจากเครื่องมือเขียนจะถูกระงับจากเซสชันอ่านอย่างเดียว และเซสชันที่จำกัดขอบเขตจะได้รับเฉพาะทักษะที่มีเครื่องมือจริงเท่านั้น แหล่งข้อมูลอยู่ใน internal/tools/skills/ หนึ่งไดเรกทอรีต่อทักษะ ในรูปแบบ Agent Skills มาตรฐาน ดังนั้นจึงสามารถคัดลอกลงในไดเรกทอรีทักษะในเครื่องได้โดยตรง

การเชื่อมต่อ

สำหรับ HTTP ที่โฮสต์ เส้นทางที่ง่ายที่สุดคือ OAuth ซึ่งไม่ต้องใช้ข้อมูลประจำตัวเลย:

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

การเรียกครั้งแรกจะเปิดเบราว์เซอร์ของคุณ คุณอนุมัติในหน้าเข้าสู่ระบบ Skycloak และเครื่องมือจะปรากฏขึ้น หากคุณเป็นสมาชิกของมากกว่าหนึ่งเวิร์กสเปซ ให้ระบุชื่อที่ต้องการ:

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

มิฉะนั้น ให้สร้างคีย์ API ในแดชบอร์ด Skycloak และกำหนดค่าไคลเอ็นต์ MCP ของคุณให้ส่งเป็น bearer token:

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

สิ่งนี้จะเพิ่มรายการต่อไปนี้ลงใน .claude.json:

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

สำหรับ stdio ในเครื่อง ให้ลงชื่อเข้าใช้ครั้งเดียว จากนั้นชี้ไคลเอ็นต์ของคุณไปที่ skycloak-mcp run:

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

Claude Desktop / Cursor (ในเครื่อง, stdio):

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

Claude Code:

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

สำหรับ headless / CI (ไม่มีเบราว์เซอร์) ให้ข้าม init และส่งคีย์แทน: เพิ่ม "env": { "SKYCLOAK_API_KEY": "sk_sc_..." } ลงในการกำหนดค่า หรือ claude mcp add skycloak --env SKYCLOAK_API_KEY=sk_sc_... -- skycloak-mcp run --transport stdio

เพิ่ม --allow-writes เฉพาะเมื่อคุณตั้งใจจะทำการเปลี่ยนแปลง (ลงชื่อเข้าใช้ด้วย skycloak-mcp init --allow-writes หรือใช้คีย์ที่จำกัดการเขียน)

เพิ่ม ?readonly=true ลงใน URL HTTP ที่โฮสต์เพื่อเปิดเผยเฉพาะเครื่องมืออ่านอย่างเดียวสำหรับเซสชัน HTTP นั้น หรือ ?readonly=false เพื่อขอพื้นผิวเครื่องมือที่รองรับการเขียน พารามิเตอร์คิวรีมีค่าเริ่มต้นเป็น false แต่เครื่องมือเขียนจะลงทะเบียนเฉพาะเมื่อเซิร์ฟเวอร์เริ่มต้นด้วย --allow-writes

เพิ่ม ?workspace=<uuid> เพื่อเลือกเวิร์กสเปซที่เซสชัน OAuth ดำเนินการ จำเป็นเฉพาะเมื่อคุณเป็นสมาชิกมากกว่าหนึ่งแห่งเท่านั้น ด้วยเวิร์กสเปซเดียวเซิร์ฟเวอร์จะเลือกให้คุณ และหากคุณเป็นสมาชิกหลายแห่งและไม่ระบุชื่อ การเชื่อมต่อจะล้มเหลวพร้อมข้อความแสดงรายการเหล่านั้น

การรัน HTTP transport

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

ไม่ต้องใช้ข้อมูลประจำตัวของตัวเอง: ผู้เรียกส่งข้อมูลของตนต่อคำขอ ดังนั้นจึงไม่มีการฉีดสิ่งใดในเวลาปรับใช้ GET /healthz และ GET /readyz ไม่ต้องรับรองความถูกต้องและรายงานเพียงว่าโพรเซสทำงานอยู่เท่านั้น โดยตั้งใจไม่ตรวจสอบ Skycloak API ดังนั้นการขัดข้องต้นทางจึงไม่ทำให้การตรวจสอบของทุก replica ล้มเหลวพร้อมกัน เซิร์ฟเวอร์ไม่เก็บสถานะเซสชัน ดังนั้น replica จึงไม่ต้องใช้ session affinity และสามารถปรับขนาดหรือหมุนเวียนได้อย่างอิสระ SIGTERM หยุดการเชื่อมต่อใหม่และระบายการเรียกที่กำลังดำเนินอยู่

เส้นทาง OAuth เปิดใช้งานเมื่อใดก็ตามที่ตั้งค่า SKYCLOAK_ISSUER และ SKYCLOAK_DASHBOARD_URL ซึ่งตั้งค่าไว้ตามค่าเริ่มต้น จากนั้น GET /.well-known/oauth-protected-resource จะถูกเสิร์ฟโดยไม่ต้องรับรองความถูกต้อง โดยระบุ realm เป็นเซิร์ฟเวอร์อนุญาต ค่า resource นำมาจาก SKYCLOAK_PUBLIC_URL เมื่อตั้งค่า และมิฉะนั้นจาก Host และ scheme ของคำขอเอง ดังนั้นการปรับใช้โฮสต์เดียวหลัง ingress จึงไม่ต้องกำหนดค่าเพิ่มเติม scheme มาจาก X-Forwarded-Proto เมื่อมี และมิฉะนั้นจะเริ่มต้นเป็น https สำหรับสิ่งใดก็ตามที่ไม่ใช่โฮสต์ loopback เนื่องจาก TLS สิ้นสุดที่ต้นทางและการเผยแพร่ตัวระบุ http:// จะไม่ตรงกับ URL ที่ไคลเอ็นต์เชื่อมต่อ ตั้งค่า SKYCLOAK_PUBLIC_URL หาก ingress ของคุณเขียน Host ใหม่ เอกสารยังระบุ openid profile email เป็น scopes_supported และความท้าทาย WWW-Authenticate ทำซ้ำเป็นพารามิเตอร์ scope ดังนั้นไคลเอ็นต์ที่อ่านอย่างใดอย่างหนึ่งจะขอจาก realm: จำเป็นต้องใช้ openid เนื่องจากการแลกเปลี่ยนโทเค็นทำให้แดชบอร์ดเรียกจุดสิ้นสุด userinfo ของ Keycloak และ Keycloak ปฏิเสธโทเค็นที่ได้รับโดยไม่มีมัน โทเค็นที่มาถึงโดยไม่มีมันจะถูกปฏิเสธที่การตรวจสอบด้วย 401 และความท้าทาย แทนที่จะนำไปสู่การแลกเปลี่ยนที่ไม่สามารถสำเร็จได้ ดังนั้นไคลเอ็นต์ที่ยังถือสิทธิ์จากก่อนหน้านี้จะหยุดลองใหม่และลงชื่อเข้าใช้อีกครั้ง การล้างตัวแปร issuer หรือแดชบอร์ดตัวใดตัวหนึ่งจะปิด OAuth ทั้งหมด และเซิร์ฟเวอร์กลับไปท้าทายคีย์ API เท่านั้น

OPENAI_APPS_CHALLENGE_TOKEN เสิร์ฟโทเค็นการตรวจสอบโดเมนไดเรกทอรีปลั๊กอินของ OpenAI ที่ /.well-known/openai-apps-challenge เป็นข้อความธรรมดาเท่านั้น หากไม่ตั้งค่า เส้นทางจะไม่ถูกลงทะเบียนและพาธจะคืนค่า 404

บันทึกการเริ่มต้นหนึ่งบรรทัดพร้อมการเชื่อมต่อที่แก้ไขแล้ว (oauth=, issuer=, dashboard=, public_url=, endpoint=, allow_writes=) เพื่อให้สามารถตรวจพบการปรับใช้ที่กำหนดค่าผิดได้โดยไม่ต้องปรับใช้ใหม่ ทุกคำขอที่ถูกปฏิเสธบนเส้นทาง OAuth จะบันทึกหนึ่งบรรทัดระบุขั้นตอนที่ล้มเหลว (verify, exchange หรือ scopes) สถานะที่ผู้เรียกได้รับ และข้อผิดพลาดพื้นฐาน ความล้มเหลวในการตรวจสอบเพิ่มการตรวจสอบที่ปฏิเสธโทเค็น (expired, wrong_issuer, bad_signature, unknown_key_id, wrong_token_type, no_openid_scope และอื่น ๆ); ความล้มเหลวในการแลกเปลี่ยนเพิ่มสถานะของแดชบอร์ดและโฮสต์ที่เรียก ผู้เรียกปรากฏเป็น subject ของโทเค็นเมื่อตรวจสอบแล้ว และไม่เคยเป็นข้อมูลประจำตัว: access token, ส่วนหัว Authorization และคีย์ API ที่สร้างขึ้นจะไม่ถูกบันทึก

การกำหนดค่า

ตัวแปรสภาพแวดล้อม	ค่าเริ่มต้น
SKYCLOAK_API_KEY	ไม่มี (ไม่บังคับสำหรับ stdio; ไคลเอ็นต์ HTTP ให้ส่วนหัว API-Key แทน)
SKYCLOAK_ENDPOINT	https://api.skycloak.io
SKYCLOAK_API_VERSION	เวอร์ชัน API ปัจจุบัน
SKYCLOAK_ISSUER	https://login.app.skycloak.io/realms/skycloak (การลงชื่อเข้าใช้ CLI และเซิร์ฟเวอร์อนุญาตที่ HTTP transport ตรวจสอบโทเค็น)
SKYCLOAK_CLIENT_ID	skycloak-mcp (เฉพาะ CLI device flow)
SKYCLOAK_DASHBOARD_URL	https://app.skycloak.io (สร้างคีย์ CLI และคีย์เซสชัน HTTP)
SKYCLOAK_PUBLIC_URL	ไม่มี (ได้มาจากแต่ละคำขอ; ตั้งค่าเมื่อ ingress เขียน Host ใหม่)
OPENAI_APPS_CHALLENGE_TOKEN	เสิร์ฟโทเค็นการตรวจสอบโดเมนไดเรกทอรีปลั๊กอินของ OpenAI ที่ /.well-known/openai-apps-challenge หากไม่ตั้งค่า พาธนั้นจะคืนค่า 404

คำสั่ง: init (ลงชื่อเข้าใช้เบราว์เซอร์), run (serve), logout (ลบคีย์ที่เก็บไว้) init ยอมรับ --workspace <id>, --allow-writes, --allow-credentials และ --ttl-days (ค่าเริ่มต้น 90)

แฟล็ก	ค่าเริ่มต้น	คำอธิบาย
--transport	stdio	stdio หรือ http
--http-addr	:8080	ที่อยู่ฟังสำหรับ HTTP transport
--allow-writes	false	เปิดใช้งานเครื่องมือแก้ไขสำหรับ stdio และอนุญาตเซสชัน HTTP ด้วย readonly=false เพื่อลงทะเบียนเครื่องมือเขียน

การพัฒนา

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

ไคลเอ็นต์ API ภายใต้ internal/apiclient สร้างจากข้อกำหนด OpenAPI ของ Skycloak ด้วย oapi-codegen

การรักษาความสอดคล้องกับ API

ไคลเอ็นต์ใน internal/apiclient สร้างจาก internal/apiclient/openapi.yaml ด้วย oapi-codegen; รัน make generate เพื่อรีเฟรช CI จะล้มเหลวหากโค้ดที่สร้างและคอมมิตแล้วเบี่ยงเบนจากข้อกำหนด คำขอจะถูกลองใหม่บน 429/5xx ด้วย backoff ที่คำนึงถึง Retry-After

การเผยแพร่

เผยแพร่เป็นไบนารี GitHub และอิมเมจคอนเทนเนอร์ ghcr.io/sky-cloak/skycloak-mcp ในแต่ละแท็ก และเผยแพร่ไปยัง MCP Registry เป็น io.skycloak/skycloak-mcp คนส่วนใหญ่ไม่จำเป็นต้องใช้ทั้งสอง: เซิร์ฟเวอร์ที่โฮสต์ไม่ต้องติดตั้ง

ความปลอดภัย

โปรดรายงานช่องโหว่เป็นการส่วนตัว ดู SECURITY.md

ผู้มีส่วนร่วม

สร้างที่ Skycloak โดย Guilliano Molaire, Neville Omangi และ Aphilas ประวัติที่เก็บถูกบีบอัดเมื่อเปิด ดังนั้นบันทึกคอมมิตจึงไม่สะท้อนว่าใครเขียนอะไร

ใบอนุญาต

Apache-2.0 คำอธิบาย OpenAPI ใน internal/apiclient/openapi.yaml สร้างจาก Skycloak platform API และเป็นลิขสิทธิ์ของ Skycloak; รวมไว้ที่นี่เพื่อให้สามารถสร้างและตรวจสอบไคลเอ็นต์ได้ ดู NOTICE