feat(auth): add personal access token (pat) support and docs

add support for plurality personal access tokens (prefixed with plur_pat_) in jwt auth middleware: verify tokens via backend pat verification endpoint, enforce mcp:tools scope, set current token/user, and return appropriate errors. introduce pat prefix constant and backend api url import. document authentication options and pat usage in README with creation, header format, and token characteristics.

Author: mujtabaidrees94

README.md

@@ -118,6 +118,29 @@ Production URL: `https://app.plurality.network/mcp`
 
 Dev URL: `https://dev.plurality.network/mcp`
 
+### Authentication — choose your method
+
+The MCP server accepts **two** auth methods:
+
+| Method | When to use | Browser required? |
+|---|---|---|
+| **OAuth 2.1 + PKCE** (Hydra) | Interactive clients: Claude Desktop, Web, Code, ChatGPT | Yes (one-time) |
+| **Personal Access Token (PAT)** | Headless agents, CI runners, custom integrations, Perplexity, n8n, LangChain | No |
+
+PATs require a **paid plan** and are managed from the **Connect via MCP** popup in the dashboard sidebar (click "Manage tokens →"). Pick OAuth if your client supports a browser; pick PAT if it doesn't.
+
+#### Using a PAT
+
+1. Sign in to the dashboard, open **Connect via MCP → Manage tokens**
+2. Click **Create token**, give it a name and optional expiry, copy the `plur_pat_…` value
+3. Configure your client to send it as a Bearer token:
+   ```
+   Authorization: Bearer plur_pat_...
+   ```
+4. Server URL is the same as for OAuth: `https://app.plurality.network/mcp`
+
+PATs auto-revoke at their expiry, can be rotated with a configurable grace period (default 7 days), and can be immediately revoked from the dashboard. They never appear in logs and are stored hashed.
+
 ### Claude Desktop / Web
 
 **Easy setup (paid plans — Pro, Max, Team, Enterprise):**

src/plurality_mcp_server/auth.py

@@ -3,7 +3,10 @@
 import time
 import httpx
 import jwt as pyjwt
-from plurality_mcp_server.config import http_client, HYDRA_ISSUER, MCP_RESOURCE_URL, current_token, current_user_id
+from plurality_mcp_server.config import http_client, HYDRA_ISSUER, MCP_RESOURCE_URL, BACKEND_API_URL, current_token, current_user_id
+
+# ── PAT prefix used by Plurality personal access tokens ──
+PAT_PREFIX = "plur_pat_"
 
 # ── JWKS cache for local JWT validation ──
 _jwks_cache: dict = {"keys": [], "fetched_at": 0}
@@ -147,6 +150,50 @@ async def __call__(self, scope, receive, send):
 
         token = auth_header.removeprefix("Bearer ").strip()
 
+        # ── Personal Access Token (PAT) path ──
+        # Validates via the backend (which owns the PAT DB). Keeps this server stateless.
+        if token.startswith(PAT_PREFIX):
+            try:
+                verify_resp = await http_client.get(
+                    f"{BACKEND_API_URL}/pat/tokens/verify",
+                    headers={"Authorization": f"Bearer {token}"},
+                    timeout=5.0,
+                )
+            except httpx.RequestError as e:
+                await self._send_json_error(scope, receive, send, 502, {
+                    "error": "pat_verify_failed",
+                    "message": f"Failed to verify PAT with backend: {str(e)}",
+                })
+                return
+
+            if verify_resp.status_code != 200:
+                err_body = {}
+                try:
+                    err_body = verify_resp.json()
+                except Exception:
+                    pass
+                await self._send_json_error(scope, receive, send, 401, {
+                    "error": err_body.get("error", "invalid_pat"),
+                    "message": "Invalid or expired API token",
+                }, {"WWW-Authenticate": f'Bearer resource_metadata="{MCP_RESOURCE_URL}/.well-known/oauth-protected-resource"'})
+                return
+
+            info = verify_resp.json()
+            pat_scopes = info.get("scopes", [])
+            if "mcp:tools" not in pat_scopes:
+                await self._send_json_error(scope, receive, send, 403, {
+                    "error": "insufficient_scope",
+                    "message": "Token missing required scope: mcp:tools",
+                }, {"WWW-Authenticate": f'Bearer error="insufficient_scope", scope="mcp:tools"'})
+                return
+
+            user_id = info.get("user_id", "")
+            print(f"[AUTH-PAT] {method} {path} | user={user_id} | token=...{token[-8:]}", flush=True)
+            current_token.set(token)
+            current_user_id.set(user_id)
+            await self.app(scope, receive, send)
+            return
+
         try:
             decoded = await verify_jwt(token)
             user_id = decoded.get("sub", "")