Skip to main content

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​

ModusWannTool-Zugriff
noneKein BearerNur read-public (öffentliche Center-Reads)
userOAuth / sk_mcp_…Effektive Rollen-/Nutzer-Matrix (unten)
legacy_fullsk_agencyos_…Alle Tools

Policy-Tiers​

TierBeispiele
read-publiccockpit_public_shops, cockpit_public_news
readcockpit_list_centers, cockpit_search_centers, cockpit_get_center, cockpit_whoami
write-contentNews, Shops, Events, Social-Entwürfe
write-configWebsite-Config, Hosting, Page-Content
destructiveLöschen, Go-Live, DNS
admin-userscockpit_list_users, cockpit_create_user, …
admin-systemOrganisation anlegen, mailcow-Instanz, Feedback-Dispatch
activityAudit, Reporting, Leaderboard (siehe unten)

Merge-Logik (Code + DB)​

  1. Codewert — ROLE_ALLOWED_TIERS in role-mcp-tool-policy.ts (Fallback ohne DB-Eintrag).
  2. Rollen-Override — Zeile in role_mcp_tier_configs (isEnabled: true|false) ersetzt den Codewert für diese Rolle × Tier.
  3. Nutzer-Override — Zeile in user_mcp_tier_configs wirkt 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​

  1. Als Super Admin anmelden.
  2. Einstellungen → Benutzer & Rollen → MCP-Berechtigungen.
  3. Pro Rolle und Kategorie den Schalter setzen (speichert DB-Override).
  4. Default entfernt den Rollen-Override — Codewert gilt wieder.
  5. Abschnitt Nutzer-Override: Nutzer wählen, Kategorien einzeln setzen; Rolle entfernt den Nutzer-Override für diese Kategorie.

API (Agenten / AgencyOS)​

RouteZweck
GET/PUT/DELETE /api/mcp-tool-policyDashboard-Session (Super Admin)
GET/PUT/DELETE /api/agencyos/v1/mcp-tool-policyPlattform-Admin-Key
GET /api/agencyos/v1/mcp-tool-policy?effective=1Effektive Tiers für Token-Inhaber
GET /api/agencyos/v1/mcp-tool-policy?userId=Matrix + selectedUser (Nutzer-Override-Ansicht)
GET /api/agencyos/v1/meFeld mcpPolicy.allowedTiers für OAuth/sk_mcp_

MCP-Tools (Super Admin via OAuth / sk_mcp_)​

ToolZweck
cockpit_mcp_tool_policy_getMatrix lesen (role?, userId?) oder effektive Tiers (effective: true)
cockpit_mcp_tool_policy_setTier-Override setzen: { role | userId, tierId, isEnabled }
cockpit_mcp_tool_policy_clearOverride 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)​

ToolZweckTier
cockpit_role_content_areas_get / _setMall-Cockpit-Bereiche pro Rolleread / admin-system
cockpit_role_modules_get / _set / _clearSidebar-Module pro Rolle (Override setzen/entfernen)read / admin-system
cockpit_role_capabilities_get / _set / _clearFähigkeiten pro Rolle, z. B. delete_contentread / 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)​

RolleActivity-ToolsCenter-SucheBenutzer-AdminSystem-Admin
SUPER_ADMINJaJaJaJa
PLATFORM_ADMINJaJaJaJa
CENTER_ADMINJaJaJa (Center-Scope)Nein
ORG_MARKETING_MANAGERJaJaNeinNein
CENTER_MANAGERNeinJaNeinNein
CONTENT_EDITORNeinJa (Lesen)NeinNein (cockpit_update_center_website_config per Allowlist — kein Hosting/Go-Live)
DEVELOPERBlockiert (Codewert)JaJaJa

Activity-Tools (Tier activity)​

  • cockpit_audit_logs
  • cockpit_user_activity
  • cockpit_employee_activity
  • cockpit_work_activity
  • cockpit_user_login_activity
  • cockpit_social_draft_activity
  • cockpit_activity_leaderboard
  • cockpit_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​

  1. cockpit_whoami — Rolle, Auth-Modus und indirekt Policy prüfen.
  2. GET /api/agencyos/v1/me — mcpPolicy.allowedTiers mit Matrix abgleichen.
  3. Dashboard → MCP-Berechtigungen — Override setzen, MCP-Client neu verbinden (Remote pro Request; Stdio ggf. Neustart).
  4. cockpit_mcp_discover_tools mit query=activity — sichtbare Tools für die Session.

Migration​

Additive SQL: packages/database/migrations/20260928180000_add_mcp_tier_config_SAFE.sql

Nutzungsstatistik: Seitenaufrufe werden anonymisiert erfasst. Im Umami-Dashboard nach diesem Pfad filtern: /en/developer-guide/mcp-role-tool-matrix