MCP: Rollen × Tool-Sichtbarkeit
Code-Basis: packages/mcp-cockpit-os/src/role-mcp-tool-policy.ts
DB-Overrides: role_mcp_tier_configs, user_mcp_tier_configs
Matrix-UI: Dashboard → Einstellungen → Benutzer & Rollen → MCP-Berechtigungen (Super Admin)
Auth-Modi
| Modus | Wann | Tool-Zugriff |
|---|---|---|
none | Kein Bearer | Nur read-public (öffentliche Center-Reads) |
user | OAuth / sk_mcp_… | Effektive Rollen-/Nutzer-Matrix (unten) |
legacy_full | sk_agencyos_… | Alle Tools |
Policy-Tiers
| Tier | Beispiele |
|---|---|
read-public | cockpit_public_shops, cockpit_public_news |
read | cockpit_list_centers, cockpit_search_centers, cockpit_get_center, cockpit_whoami |
write-content | News, Shops, Events, Social-Entwürfe |
write-config | Website-Config, Hosting, Page-Content |
destructive | Löschen, Go-Live, DNS |
admin-users | cockpit_list_users, cockpit_create_user, … |
admin-system | Organisation anlegen, mailcow-Instanz, Feedback-Dispatch |
activity | Audit, Reporting, Leaderboard (siehe unten) |
Merge-Logik (Code + DB)
- Codewert —
ROLE_ALLOWED_TIERSinrole-mcp-tool-policy.ts(Fallback ohne DB-Eintrag). - Rollen-Override — Zeile in
role_mcp_tier_configs(isEnabled: true|false) ersetzt den Codewert für diese Rolle × Tier. - Nutzer-Override — Zeile in
user_mcp_tier_configswirkt zusätzlich auf den Nutzer (OAuth / sk_mcp_).
Super Admin (immun): Rollen-Overrides für SUPER_ADMIN sind gesperrt — API PUT/DELETE mit role: SUPER_ADMIN → 403; UI-Schalter disabled. Effektive Tiers kommen immer aus dem Codewert (ggf. plus Nutzer-Override auf einzelne Super-Admin-Accounts).
Developer erscheint in der Dashboard-Matrix (ALL_USER_ROLES); Activity-Tier bleibt im Codewert blockiert (role-mcp-tool-policy.ts), kann aber per Rollen-Override freigeschaltet werden.
Integrations-Keys (sk_agencyos_) umgehen die Matrix (legacy_full).
Dashboard bearbeiten
- Als Super Admin anmelden.
- Einstellungen → Benutzer & Rollen → MCP-Berechtigungen.
- Pro Rolle und Kategorie den Schalter setzen (speichert DB-Override).
- Default entfernt den Rollen-Override — Codewert gilt wieder.
- Abschnitt Nutzer-Override: Nutzer wählen, Kategorien einzeln setzen; Rolle entfernt den Nutzer-Override für diese Kategorie.
API (Agenten / AgencyOS)
| Route | Zweck |
|---|---|
GET/PUT/DELETE /api/mcp-tool-policy | Dashboard-Session (Super Admin) |
GET/PUT/DELETE /api/agencyos/v1/mcp-tool-policy | Plattform-Admin-Key |
GET /api/agencyos/v1/mcp-tool-policy?effective=1 | Effektive Tiers für Token-Inhaber |
GET /api/agencyos/v1/mcp-tool-policy?userId= | Matrix + selectedUser (Nutzer-Override-Ansicht) |
GET /api/agencyos/v1/me | Feld mcpPolicy.allowedTiers für OAuth/sk_mcp_ |
MCP-Tools (Super Admin via OAuth / sk_mcp_)
| Tool | Zweck |
|---|---|
cockpit_mcp_tool_policy_get | Matrix lesen (role?, userId?) oder effektive Tiers (effective: true) |
cockpit_mcp_tool_policy_set | Tier-Override setzen: { role | userId, tierId, isEnabled } |
cockpit_mcp_tool_policy_clear | Override entfernen (Codewert-Default) |
Schreiben (set/clear) = Tier admin-system — nur Super Admin / Developer / globaler AgencyOS-Key. Lesen der Matrix ebenfalls Plattform-Admin; effective=true für jeden authentifizierten User-Token.
Rollen-Matrizen (Bereiche, Module, Fähigkeiten)
| Tool | Zweck | Tier |
|---|---|---|
cockpit_role_content_areas_get / _set | Mall-Cockpit-Bereiche pro Rolle | read / admin-system |
cockpit_role_modules_get / _set / _clear | Sidebar-Module pro Rolle (Override setzen/entfernen) | read / admin-system |
cockpit_role_capabilities_get / _set / _clear | Fähigkeiten pro Rolle, z. B. delete_content | read / admin-system |
Schreiben nur Super Admin / Developer / globaler AgencyOS-Key; die API prüft zusätzlich Plattform-Admin. Routen: AgencyOS-Integration.
Body für PUT: { "role": "CONTENT_EDITOR", "tierId": "destructive", "isEnabled": false }
Nutzer-Override: { "userId": "<uuid>", "tierId": "activity", "isEnabled": true }
Rollen-Übersicht (Codewert, Kernrollen)
| Rolle | Activity-Tools | Center-Suche | Benutzer-Admin | System-Admin |
|---|---|---|---|---|
| SUPER_ADMIN | Ja | Ja | Ja | Ja |
| PLATFORM_ADMIN | Ja | Ja | Ja | Ja |
| CENTER_ADMIN | Ja | Ja | Ja (Center-Scope) | Nein |
| ORG_MARKETING_MANAGER | Ja | Ja | Nein | Nein |
| CENTER_MANAGER | Nein | Ja | Nein | Nein |
| CONTENT_EDITOR | Nein | Ja (Lesen) | Nein | Nein (cockpit_update_center_website_config per Allowlist — kein Hosting/Go-Live) |
| DEVELOPER | Blockiert (Codewert) | Ja | Ja | Ja |
Activity-Tools (Tier activity)
cockpit_audit_logscockpit_user_activitycockpit_employee_activitycockpit_work_activitycockpit_user_login_activitycockpit_social_draft_activitycockpit_activity_leaderboardcockpit_zero_activity_report
Fehler bei verweigertem Tool
Remote-MCP antwortet mit HTTP 403:
{
"success": false,
"error": "MCP-Tool „…\" ist für Rolle … nicht freigegeben …",
"code": "ERR_MCP_TOOL_DENIED",
"tool": "cockpit_user_activity",
"role": "CONTENT_EDITOR"
}
So testen
cockpit_whoami— Rolle, Auth-Modus und indirekt Policy prüfen.GET /api/agencyos/v1/me—mcpPolicy.allowedTiersmit Matrix abgleichen.- Dashboard → MCP-Berechtigungen — Override setzen, MCP-Client neu verbinden (Remote pro Request; Stdio ggf. Neustart).
cockpit_mcp_discover_toolsmitquery=activity— sichtbare Tools für die Session.
Migration
Additive SQL: packages/database/migrations/20260928180000_add_mcp_tier_config_SAFE.sql
Links
Nutzungsstatistik: Seitenaufrufe werden anonymisiert erfasst. Im Umami-Dashboard nach diesem Pfad filtern: /en/developer-guide/mcp-role-tool-matrix