Add auth token privilege cap setting

Author: mneudert

API.php

@@ -20,6 +20,7 @@
 use Piwik\NoAccessException;
 use Piwik\Piwik;
 use Piwik\Http\BadRequestException;
+use Piwik\Plugins\McpServer\Support\Access\McpAccessLevel;
 use Piwik\Plugins\McpServer\Support\Api\JsonRpcErrorResponseFactory;
 use Piwik\Plugins\McpServer\Support\Api\JsonRpcRequestIdExtractor;
 use Piwik\Plugins\McpServer\Support\Api\McpEndpointGuard;
@@ -96,6 +97,10 @@ public function mcp(): ResponseInterface
             return $this->createDisabledResponse($requestMetadata['topLevelRequestId']);
         }
 
+        if (!$this->isCurrentUserPrivilegeLevelAllowed()) {
+            return $this->createPrivilegeTooHighResponse($requestMetadata['topLevelRequestId']);
+        }
+
         try {
             $server = $this->factory->createServer();
             $transport = new StreamableHttpTransport($request);
@@ -137,6 +142,14 @@ protected function isMcpEnabled(): bool
         return $this->systemSettings->isMcpEnabled();
     }
 
+    protected function isCurrentUserPrivilegeLevelAllowed(): bool
+    {
+        return !McpAccessLevel::exceedsMaximumAllowed(
+            McpAccessLevel::resolveCurrentUserLevel(),
+            $this->systemSettings->getMaximumAllowedMcpAccessLevel()
+        );
+    }
+
     protected function isCurrentApiRequestRoot(): bool
     {
         return ApiRequest::isCurrentApiRequestTheRootApiRequest();
@@ -175,4 +188,18 @@ protected function createDisabledResponse(string|int|null $topLevelRequestId): R
             $topLevelRequestId
         );
     }
+
+    protected function createPrivilegeTooHighResponse(string|int|null $topLevelRequestId): ResponseInterface
+    {
+        if ($topLevelRequestId === null) {
+            return (new Psr17Factory())->createResponse(403);
+        }
+
+        return $this->jsonRpcErrorResponseFactory->create(
+            403,
+            JsonRpcError::INVALID_REQUEST,
+            McpAccessLevel::createTooHighPrivilegeMessage($this->systemSettings->getMaximumAllowedMcpAccessLevel()),
+            $topLevelRequestId
+        );
+    }
 }

README.md

@@ -12,6 +12,7 @@ It provides analytics tools for sites, reports, processed report data, goals, se
 2. Activate **McpServer** in **Administration -> Plugins**.
 3. Enable MCP in **Administration -> System -> Plugin Settings -> McpServer**.
 4. Configure your MCP client with the endpoint and a Matomo `token_auth` that already has access to the data you want to expose.
+5. If needed, restrict the maximum allowed MCP privilege level in plugin settings or use a separate lower-privilege Matomo user for MCP access.
 
 For the recommended end-user setup flow, use the in-product connect guide at **Administration -> Platform -> MCP Server**.
 
@@ -21,6 +22,7 @@ For the recommended end-user setup flow, use the in-product connect guide at **A
 - Raw Matomo API discovery and execution tools are separately disabled by default and must be enabled by an administrator.
 - The plugin uses Matomo authentication.
 - Data access is limited to the same sites and reports the Matomo user can already access.
+- Administrators can optionally restrict MCP usage to users or tokens at or below a configured privilege level.
 - When raw API access is enabled, MCP clients can access the same Matomo API surface available to the authenticated user, including state-changing methods if an administrator has allowed them.
 - If features such as the Visitor Log are available to that user, MCP clients may access the same underlying data scope.
 - Review privacy, security, and compliance requirements before enabling raw API access.

Support/Access/McpAccessLevel.php

@@ -0,0 +1,111 @@
+<?php
+
+/**
+ * Matomo - free/libre analytics platform
+ *
+ * @link    https://matomo.org
+ * @license https://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
+ */
+
+declare(strict_types=1);
+
+namespace Piwik\Plugins\McpServer\Support\Access;
+
+use Piwik\Access;
+use Piwik\Piwik;
+use Piwik\Plugins\McpServer\Support\Api\McpEndpointSpec;
+
+final class McpAccessLevel
+{
+    public const UNLIMITED = 'unlimited';
+    public const VIEW = 'view';
+    public const WRITE = 'write';
+    public const ADMIN = 'admin';
+    public const SUPERUSER = 'superuser';
+
+    /**
+     * @return list<string>
+     */
+    public static function getConfigurableLevels(): array
+    {
+        return [
+            self::UNLIMITED,
+            self::VIEW,
+            self::WRITE,
+            self::ADMIN,
+        ];
+    }
+
+    public static function normalizeMaximumAllowed(mixed $value): string
+    {
+        if (!is_scalar($value)) {
+            return self::UNLIMITED;
+        }
+
+        $normalizedValue = strtolower(trim((string) $value));
+
+        return in_array($normalizedValue, self::getConfigurableLevels(), true)
+            ? $normalizedValue
+            : self::UNLIMITED;
+    }
+
+    public static function resolveCurrentUserLevel(): string
+    {
+        $access = Access::getInstance();
+
+        if ($access->hasSuperUserAccess()) {
+            return self::SUPERUSER;
+        }
+
+        if (Piwik::isUserHasSomeAdminAccess()) {
+            return self::ADMIN;
+        }
+
+        if (Piwik::isUserHasSomeWriteAccess()) {
+            return self::WRITE;
+        }
+
+        return self::VIEW;
+    }
+
+    public static function exceedsMaximumAllowed(string $currentLevel, string $maximumAllowedLevel): bool
+    {
+        $normalizedMaximum = self::normalizeMaximumAllowed($maximumAllowedLevel);
+
+        if ($normalizedMaximum === self::UNLIMITED) {
+            return false;
+        }
+
+        return self::getRank($currentLevel) > self::getRank($normalizedMaximum);
+    }
+
+    public static function getDisplayName(string $level): string
+    {
+        return match ($level) {
+            self::VIEW => 'View',
+            self::WRITE => 'Write',
+            self::ADMIN => 'Admin',
+            self::SUPERUSER => 'Superuser',
+            default => 'Unlimited',
+        };
+    }
+
+    public static function createTooHighPrivilegeMessage(string $maximumAllowedLevel): string
+    {
+        return sprintf(
+            McpEndpointSpec::TOO_HIGH_PRIVILEGE_ERROR,
+            self::getDisplayName(self::normalizeMaximumAllowed($maximumAllowedLevel))
+        );
+    }
+
+    private static function getRank(string $level): int
+    {
+        return match ($level) {
+            self::VIEW => 1,
+            self::WRITE => 2,
+            self::ADMIN => 3,
+            self::SUPERUSER => 4,
+            default => 0,
+        };
+    }
+}

Support/Api/McpEndpointSpec.php

@@ -22,5 +22,7 @@ final class McpEndpointSpec
         . 'Nested API calls (including API.getBulkRequest) are not supported.';
     public const UNAUTHORIZED_ERROR = 'Authentication required.';
     public const DISABLED_ERROR = 'MCP endpoint is disabled. Please contact your Matomo administrator.';
+    public const TOO_HIGH_PRIVILEGE_ERROR =
+        'Authenticated MCP access has too high privilege level. Maximum of %s access level is allowed.';
     public const INTERNAL_ERROR = 'Internal endpoint error.';
 }

SystemSettings.php

@@ -15,6 +15,7 @@
 use Piwik\Settings\FieldConfig;
 use Piwik\Settings\Setting;
 use Piwik\SettingsPiwik;
+use Piwik\Plugins\McpServer\Support\Access\McpAccessLevel;
 use Piwik\Plugins\McpServer\Support\Access\RawApiAccessMode;
 
 class SystemSettings extends \Piwik\Settings\Plugin\SystemSettings
@@ -26,6 +27,9 @@ class SystemSettings extends \Piwik\Settings\Plugin\SystemSettings
     /** @var Setting */
     public $enableMcp;
 
+    /** @var Setting */
+    public $maximumMcpAccessLevel;
+
     /** @var Setting */
     public $rawApiAccessScope;
 
@@ -63,6 +67,27 @@ function (FieldConfig $field) {
             }
         );
 
+        $this->maximumMcpAccessLevel = $this->makeSetting(
+            'maximum_mcp_access_level',
+            McpAccessLevel::UNLIMITED,
+            FieldConfig::TYPE_STRING,
+            function (FieldConfig $field) {
+                $field->title = Piwik::translate('McpServer_MaximumMcpAccessLevelTitle');
+                $field->inlineHelp = implode('<br><br>', [
+                    Piwik::translate('McpServer_MaximumMcpAccessLevelHelpPurpose'),
+                    Piwik::translate('McpServer_MaximumMcpAccessLevelHelpTokens'),
+                    Piwik::translate('McpServer_MaximumMcpAccessLevelHelpSeparateUser'),
+                ]);
+                $field->uiControl = FieldConfig::UI_CONTROL_SINGLE_SELECT;
+                $field->availableValues = [
+                    McpAccessLevel::UNLIMITED => Piwik::translate('McpServer_MaximumMcpAccessLevelUnlimited'),
+                    McpAccessLevel::VIEW => Piwik::translate('McpServer_MaximumMcpAccessLevelView'),
+                    McpAccessLevel::WRITE => Piwik::translate('McpServer_MaximumMcpAccessLevelWrite'),
+                    McpAccessLevel::ADMIN => Piwik::translate('McpServer_MaximumMcpAccessLevelAdmin'),
+                ];
+            }
+        );
+
         $sharedRawApiInlineHelp = implode('<br><br>', [
             Piwik::translate('McpServer_RawApiAccessHelpPurpose'),
             Piwik::translate('McpServer_RawApiAccessHelpReadFallback'),
@@ -137,6 +162,11 @@ public function isMcpEnabled(): bool
         return (bool) $this->enableMcp->getValue();
     }
 
+    public function getMaximumAllowedMcpAccessLevel(): string
+    {
+        return McpAccessLevel::normalizeMaximumAllowed($this->maximumMcpAccessLevel->getValue());
+    }
+
     public function getRawApiAccessMode(): string
     {
         $scope = $this->normalizeRawApiAccessScope($this->rawApiAccessScope->getValue());

docs/faq.md

@@ -38,6 +38,13 @@ Configure raw Matomo API tool access in **Administration -> System -> Plugin Set
 - Low-confidence or unclassified direct API methods require `Full API access`.
 - Direct API access can expose raw or personal data depending on enabled Matomo features. Review privacy and security requirements before enabling it, and consult your DPO or compliance owner when needed.
 
+Configure MCP privilege limits in **Administration -> System -> Plugin Settings -> McpServer**:
+
+- Use **Maximum allowed MCP privilege level** to deny MCP access for users authenticated with a higher Matomo privilege.
+- `No privilege limit` (default): follows the usual Matomo access model and does not add an extra MCP privilege cap.
+- `View access`, `Write access`, or `Admin access`: allows only users whose highest privilege across all sites is at or below the selected level.
+- For stricter separation, create a separate Matomo user or token with reduced permissions for MCP use.
+
 ## Enabling MCP
 
 MCP access is disabled by default and must be enabled in **Administration -> System -> Plugin Settings -> McpServer**.
@@ -62,5 +69,5 @@ The plugin is focused on read-oriented analytics workflows. The exact tool surfa
 ## Troubleshooting
 
 - `401 Unauthorized`: verify the Bearer token is present, active, and belongs to a user with access to the requested site data.
-- `403 Forbidden`: if MCP is disabled, enable MCP in **Administration -> System -> Plugin Settings -> McpServer**. If MCP is already enabled, verify the authenticated Matomo user has access to the requested site or report data.
+- `403 Forbidden`: if MCP is disabled, enable MCP in **Administration -> System -> Plugin Settings -> McpServer**. If MCP is already enabled, verify the authenticated Matomo user has access to the requested site or report data and does not exceed the configured maximum MCP privilege level.
 - `400 Bad Request`: verify the client is using the exact MCP endpoint and is not proxying requests through `API.getBulkRequest`.

lang/en.json

@@ -32,6 +32,14 @@
         "EnableMcpHelpPurpose": "Enable the Matomo MCP Server (Model Context Protocol) to allow AI tools and assistants to access analytics context from your Matomo instance.",
         "EnableMcpHelpUrl": "Your MCP URL: %1$s%2$s%3$s",
         "EnableMcpTitle": "Enable MCP Server (Model Context Protocol)",
+        "MaximumMcpAccessLevelAdmin": "Admin access",
+        "MaximumMcpAccessLevelHelpPurpose": "Choose the highest Matomo privilege level allowed to use the MCP endpoint. Users authenticated with a higher privilege level will be denied.",
+        "MaximumMcpAccessLevelHelpSeparateUser": "If you need tighter isolation, create a separate Matomo user for MCP with only the required site permissions.",
+        "MaximumMcpAccessLevelHelpTokens": "Use this setting to limit MCP access to lower-privilege users or tokens.",
+        "MaximumMcpAccessLevelTitle": "Maximum allowed MCP privilege level",
+        "MaximumMcpAccessLevelUnlimited": "No privilege limit",
+        "MaximumMcpAccessLevelView": "View access",
+        "MaximumMcpAccessLevelWrite": "Write access",
         "RawApiAccessHelpDataScope": "Direct Matomo API access can expose the same data available through the Matomo user interface or direct API endpoints, including raw or personal data when features such as the Visitor Log are enabled.",
         "RawApiAccessHelpDestructive": "Partial API access can enable create, update, and delete methods through the selected checkboxes below. Full API access can execute any allowed state-changing or destructive API methods, including actions that modify configuration or delete data.",
         "RawApiAccessHelpPolicy": "Before enabling direct API access, ensure this complies with your organization's privacy and security policies and applicable regulations. You may need approval from your data protection officer (DPO) or another compliance owner.",