Skip to main content

How to configure role permissions

AI Copilot uses Magento's role-based access control (ACL) to determine which tools each admin user can access. You can also configure per-role restrictions for the Database Reader tool.

Tool permissions​

  1. Navigate to System -> Permissions -> User Roles and click on a role.

  2. Open the Role Resources tab.

  3. Expand the MCP Tools section.

  4. Enable or disable individual tools:

    • MCP Tools
      • Built in
        • System
          • Store Info — access to store configuration data
          • GraphQL Query — execute GraphQL queries and mutations
          • Database Reader — execute read-only SQL queries
          • REST API — call Magento REST API endpoints
          • Cache Manager — list, clean, flush, enable, and disable cache types
          • Cron Checker — diagnose cron health and job run history
          • Indexer — list indexer status and invalidate indexers
          • Log Reader — inspect var/log and var/report files

  5. Click Save Role.

note

Copilot can only use tools that are enabled for the logged-in admin user's role. If a tool is disabled in the role, Copilot will not be able to use it.

Widget Configuration permission​

The Widget Configuration resource controls who can customize the Copilot chat widget (colors, launcher, welcome screen, featured prompts, recent-conversations list). It is independent of the tool permissions above.

  1. Navigate to System -> Permissions -> User Roles and click on a role.
  2. Open the Role Resources tab.
  3. Expand Stores -> Settings -> Configuration -> AI Copilot and enable Widget Configuration.
  4. Click Save Role.

Admins in this role see a gear icon on the Copilot welcome screen and can open the widget configuration panel. Admins without the permission still use Copilot normally — they just don't see the gear.

Widget configuration is shared across all admins on the same Magento instance — it is not per-user.

REST API endpoint permissions​

The REST API tool requires two levels of permissions:

  1. The MCP Tools -> Built in -> System -> REST API resource must be enabled (gives access to the tool itself).
  2. Each REST API endpoint is protected by its own Magento ACL resource. For example, to allow Copilot to manage products via REST API, the role needs both the REST API tool permission and the Catalog -> Inventory -> Products resource.

Database Reader restrictions per role​

In addition to ACL-based tool access, you can configure per-role restrictions for which database tables the Database Reader tool can access.

  1. Navigate to System -> Permissions -> User Roles and click on a role.

  2. Open the MCP Info tab.

  3. Configure the Database Reader Security section:

    • Access mode:

      • Use Global Settings: inherits the access mode from global configuration
      • Blacklist: tables matching the patterns are blocked for this role
      • Whitelist: only tables matching the patterns are accessible for this role

    • Table patterns: one pattern per line. Use * as a wildcard. These patterns are applied in addition to global settings.

  4. Click Save Role.

Log Reader restrictions per role​

In addition to ACL-based tool access, you can configure per-role restrictions for which var/log files the Log Reader tool can access.

  1. Navigate to System -> Permissions -> User Roles and click on a role.
  2. Open the MCP Info tab.
  3. Configure the Accessible var/log File Patterns field: one file-name pattern per line. Use * as a wildcard. Leave empty to inherit the global patterns.
  4. Click Save Role.

Files under var/report are always accessible regardless of these patterns.

Cache Manager and Indexer permissions​

Two of the system tools require core Magento permissions in addition to the tool ACL resource:

  • Cache Manager write actions map to core Cache Management permissions: clean requires Flush Magento Cache, flush requires Flush Cache Storage, and enable/disable require Toggle Cache Type. The status action is always available.
  • Indexer invalidation requires both the System -> Index Management -> Invalidate index permission and the store-configuration Allow Index Invalidation switch (see Tools Settings). The status action is always available.

How global and role patterns combine​

Both global and role-specific patterns are enforced. Role patterns add restrictions on top of global settings — they cannot grant access to tables blocked by global configuration.

Example:

  • Global setting: whitelist mode with sales_*, catalog_*
  • Role setting: whitelist mode with sales_order

Result: the user with this role can only access the sales_order table. Even though the global whitelist allows all sales_* and catalog_* tables, the role whitelist further restricts access to just sales_order.