Permissions Matrix

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

​

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

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)

Cannot ban users, cannot assign to others.

​

learner

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