> ## Documentation Index > Fetch the complete documentation index at: https://docs.konstantly.com/llms.txt > Use this file to discover all available pages before exploring further. # Permissions Matrix > Which Konstantly role unlocks which MCP tool, and how license tier interacts MCP keys do not have their own permission system. They inherit **the permissions of the user who issued them**, exactly as if that user had clicked the equivalent button in the browser UI. This page maps each MCP tool to the underlying permission alias and shows which built-in roles get it. ## Quick rules 1. **Every tool call re-resolves permissions fresh** against the owning user's current role. Revoke a permission → the next MCP call respects it immediately. No cache to invalidate. 2. **License tier `restrictions.mcpAccess` is the upper bound**: * `"none"` → MCP server disabled entirely (401) * `"read"` → all write scopes clamped to false; only read tools available * `"full"` → both read and write tools available per key scope 3. **`restrictions.mcpAiAccess` is a separate, additional gate** for the AI course-generation tools. Requires `mcpAccess: "full"` AND `mcpAiAccess: true`. Default on for Business and Enterprise; can be flipped off per-tenant for abuse mitigation. 4. **The `mcp_manage` permission gates KEY CREATION/REVOCATION**, not key USAGE. A user without `mcp_manage` cannot create new keys but their existing keys keep working until revoked. ## Tool → permission map | Tool | Required permission alias | R/W | License tier needed | | ------------------------------ | ------------------------------------------------- | --- | ------------------------ | | `find_user` | `user_view` | R | read | | `get_user` | `user_view` | R | read | | `find_course` | `course_view` | R | read | | `get_course` | `course_view` | R | read | | `list_assignments` | `user_assign` | R | read | | `list_my_assignments` | any role (learner+) | R | read | | `get_compliance_status` | `common_stat` | R | read | | `list_certificates` | `user_view` | R | read | | `get_statistics` | `common_stat` | R | read | | `get_leaderboard` | `common_stat` | R | read | | `get_audit_log` | `audit_view` | R | read | | `assign_training` | `user_assign` | W | **full** | | `bulk_assign` | `group_assign` | W | **full** | | `assign_chain` | `user_assign` + chain ownership | W | **full** | | `ban_user` | `user_ban` + role hierarchy | W | **full** | | `unban_user` | `user_ban` + role hierarchy | W | **full** | | `change_user_email` | `user_edit` + role hierarchy | W | **full** | | `clone_course` | `course_edit` | W | **full** | | `upload_source_material` | `course_edit` | W | **full** + `mcpAiAccess` | | `create_course_from_prompt` | `course_edit` | W | **full** + `mcpAiAccess` | | `create_course_from_files` | `course_edit` | W | **full** + `mcpAiAccess` | | `get_course_generation_status` | `course_edit` (write-scope only) | W | **full** + `mcpAiAccess` | | `refine_course` | `course_edit` **on the specific course** | W | **full** + `mcpAiAccess` | | `regenerate_question` | `course_edit` **on the question's parent course** | W | **full** + `mcpAiAccess` | | `regenerate_lesson` | `course_edit` **on the lesson's parent course** | W | **full** + `mcpAiAccess` | ## Role → tool map (built-in roles) These are the default permissions on the stock Konstantly roles. Your tenant may have customized roles; check **Settings → Roles** for what each of yours actually grants. ### `super_user` Implicitly has all permissions. Every tool is available. ### `administrator` | Available tools | Permission | | ---------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | | All read tools | (has all read perms) | | `assign_training`, `bulk_assign`, `assign_chain` | `user_assign`, `group_assign` | | `ban_user`, `unban_user` | `user_ban` | | `change_user_email` | `user_edit` | | `clone_course` | `course_edit` | | AI course generation (`upload_source_material`, `create_course_from_prompt`, `create_course_from_files`, `get_course_generation_status`) | `course_edit` + `mcpAiAccess` license flag | | AI course refinement (`refine_course`, `regenerate_question`, `regenerate_lesson`) | `course_edit` on the specific course + `mcpAiAccess` | | Audit access | `audit_view` | | MCP key management | `mcp_manage` (seeded with the MCP feature) | In practice, an admin's MCP key is functionally equivalent to a super-user key for tool access (they have all the same aliases). ### `expert` / `instructor` (course creators) | Available tools | | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `find_user`, `find_course`, `get_course`, `list_my_assignments`, `list_certificates`, `get_statistics`, `get_leaderboard` (read access) | | `clone_course` | | AI course generation tools — when the tenant has the `mcpAiAccess` license flag enabled, course-creator roles get these four tools too (`course_edit` is the only required alias) | | AI course refinement tools (`refine_course`, `regenerate_question`, `regenerate_lesson`) — same license flag, but each call additionally requires that the user can edit THIS course (per-course access check, not just the role alias) | Cannot ban users, cannot assign to others. ### `learner` | Available tools | | ----------------------------------------------------------------------------- | | `list_my_assignments`, `find_course`, `get_course`, `list_certificates` (own) | The narrowest tool set. A learner-issued key cannot read other learners' data or take admin actions. ## Permission hierarchy enforcement Three tools enforce **role-hierarchy** on top of the basic permission check: * `ban_user`, `unban_user`: caller must outrank the target user * `change_user_email`: caller must outrank the target user Hierarchy is checked exactly as in the web UI (via the same `canAssignRole` / `hasUserAccessToUser` helpers). A manager-level user cannot ban an admin; an admin cannot change a super-user's email. If the hierarchy check fails, the tool returns: > *"Permission denied — your user does not have rights for this action."* ## License tier behavior in detail ### License-clamp scenario You issued a key with `scopes = { read: true, write: true }`. The tenant's `mcpAccess` is later clamped to `"read"` (e.g. abuse mitigation, or a downgrade to a tier that doesn't include MCP). The next MCP call from that key: 1. Authenticates successfully (key still valid) 2. License tier is read at request time → `"read"` 3. Effective scopes after clamp: `{ read: true, write: false }` 4. Write tool invocations 403; read tool invocations succeed **No re-issue required.** The clamp is dynamic. If `mcpAccess` returns to `"full"`, the same key regains write capability without any action. The capabilities endpoint reflects the effective scopes at the time it's called, so the MCP server will deregister write tools from the LLM on next startup. ### Read-only-key scenario You issued a key with `scopes = { read: true, write: false }`. The key always behaves read-only — even if `mcpAccess` allows write — because **stored scopes are the floor**: 1. Authenticates successfully 2. License tier permits write 3. But the key's STORED scopes are still `{ read: true, write: false }` 4. Effective scopes: `{ read: true, write: false }` To grant write to that key, **revoke + re-issue** with `write: true`. Stored scopes are not upgraded automatically. ## Auditing who did what Every MCP write-tool call writes two entries to the audit log: 1. The **action event** (e.g., `COURSE_ASSIGN`) — same as a UI-driven action would write 2. An **`MCP_TOOL_CALL` event** (event type 88, target type `MCP_API_KEY`) with `data: {tool, tier, ...args}` This lets compliance reports filter "actions taken by an agent vs by a human admin". Query the audit log for `eventType=88` to see the MCP-driven action history. `MCP_TOOL_CALL` is emitted only on **write** tools — read tools are too high-volume to log per-call and are tracked in the AI Usage dashboard alongside other AI-driven activity. ## Next steps All 25 tools with parameters Rate limits, key hygiene, audit