diff --git a/docs/superpowers/specs/2026-07-13-mcp-oauth-scope-b2-design.md b/docs/superpowers/specs/2026-07-13-mcp-oauth-scope-b2-design.md
new file mode 100644
index 0000000..81c61b3
--- /dev/null
+++ b/docs/superpowers/specs/2026-07-13-mcp-oauth-scope-b2-design.md
@@ -0,0 +1,286 @@
+# Scope B2 — Serveur d'autorisation OAuth 2.1 pour le connecteur MCP
+
+**Issue :** #114 (« Permettre l'accès aux données colibre via ChatGPT et Claude.ai »),
+2ᵉ partie de #111.
+**Date :** 2026-07-13
+**Statut :** design approuvé
+**Prérequis :** scopes A et B livrés et fusionnés dans `dev` (serveur MCP `/_mcp`,
+`src/mcp/`, garde jeton statique `src/mcp/auth.py`, page `/compte/mcp`).
+
+## Objectif
+
+Permettre aux clients grand public qui exigent OAuth — **Claude.ai, Claude Desktop,
+Claude mobile, ChatGPT** — de se connecter au serveur MCP colibre sans copier-coller
+de jeton, en faisant de colibre son **propre serveur d'autorisation OAuth 2.1**
+conforme à la spec MCP (authorization, 2025-06-18 / 2025-11-25). L'accès reste
+**conditionné à un abonnement colibre actif**, vérifié à chaque requête.
+
+Le chemin « jeton statique » livré en scope B (clients CLI : Claude Code, Gemini,
+Mistral) est **conservé sans régression**. Ce scope l'**ajoute** en parallèle.
+
+## Décisions de conception (arbitrées)
+
+1. **colibre = serveur d'autorisation ET resource server**, sur le même Flask
+ (`app.server`) qui sert déjà `/_mcp`. L'étape de consentement réutilise la
+ **session flask_login existante**.
+2. **authlib** (déjà en dépendance pour LinkedIn) via son cœur OAuth 2.0
+ (`authlib.oauth2.rfc6749/7591/7636/8414`), avec un **stockage SQLite maison**
+ (`sqlite3` brut, comme `tokens_db.py` / `auth.db` / `subscriptions.db`). Pas de
+ SQLAlchemy.
+3. **Tokens d'accès opaques**, validés par lookup haché en base (colibre étant AS
+ **et** RS sur le même hôte). Pas de JWT/JWKS/signature. L'audience (`resource`)
+ est stockée sur la ligne du token.
+4. **DCR (RFC 7591) comme baseline** d'enregistrement client. Claude et ChatGPT le
+ supportent nativement et retombent dessus si CIMD n'est pas annoncé. Clients
+ **publics** (`token_endpoint_auth_methods_supported: ["none"]` + PKCE S256).
+5. **Gate abonnement bloquant tôt, à `/authorize`**, ET re-vérifié à chaque requête
+ `/_mcp` et à chaque refresh (défense en profondeur — voir §« Abonnement »).
+6. **Détection d'usage (niveau 1)** : table `mcp_usage` journalisant chaque requête
+ `/_mcp` authentifiée. Pas de rate-limiting actif (hors-périmètre).
+7. **Durées de vie** : access token **1 h**, refresh token **60 j**, **rotation du
+ refresh** à chaque usage (exigence client public).
+
+## Exigences externes vérifiées (2026-07)
+
+Sources : spec MCP authorization (2025-06-18/2025-11-25), doc connecteurs Claude
+(`claude.com/docs/connectors/building/authentication`), doc Apps SDK ChatGPT
+(`developers.openai.com/apps-sdk/build/auth`).
+
+Communes à Claude **et** ChatGPT :
+
+- **Découverte** : PRM (RFC 9728) à `/.well-known/oauth-protected-resource`
+ (+ variante suffixée `/_mcp`) ; AS metadata (RFC 8414) à
+ `/.well-known/oauth-authorization-server` ; **`/.well-known/openid-configuration`**
+ aussi (sondé par ChatGPT). Le champ `resource` de la PRM doit valoir **exactement**
+ l'URL saisie par l'utilisateur (`https://colibre.fr/_mcp`) ; `authorization_servers`
+ liste l'issuer, **1ʳᵉ entrée utilisée** (pas de fallback vers les suivantes).
+- **401 + `WWW-Authenticate: Bearer …, resource_metadata="…"`** : c'est ce header
+ qui déclenche le flux OAuth côté client. Le 401 (pas 200) est requis.
+- **PKCE S256** obligatoire ; metadata doit annoncer
+ `code_challenge_methods_supported: ["S256"]`.
+- **Audience RFC 8707** : `resource` envoyé sur `/authorize` et `/token`, copié sur
+ le token, validé à `/_mcp`.
+- **`/token`** accepte `application/x-www-form-urlencoded`, renvoie des codes
+ d'erreur **RFC 6749** (`invalid_grant`). `/register` en `application/json`.
+- **Refresh** : Claude fait la **rotation** (client public) et n'ajoute
+ `offline_access` que si annoncé dans `scopes_supported`. ChatGPT ne l'exige pas.
+ → on supporte le refresh et on annonce `offline_access`.
+- **Redirect URIs** validés en **exact-match** contre ceux fournis au DCR :
+ Claude `https://claude.ai/api/mcp/auth_callback` ; ChatGPT
+ `https://chatgpt.com/connector/oauth/{id}` (+ legacy
+ `https://chatgpt.com/connector_platform_oauth_redirect`). Rien à coder en dur.
+- **Consentement** : l'écran doit afficher le **hostname du redirect_uri** (risque
+ d'usurpation loopback, spec 2025-11-25).
+- **Latence** : discovery/registration/token < 10 s, refresh < 30 s (les opérations
+ sqlite sont bien en-deçà).
+- **Ops** : l'AS et `/_mcp` doivent rester joignables depuis l'egress Anthropic
+ `160.79.104.0/21` sans WAF bloquant, en **HTTPS** (localhost toléré en dev).
+
+## Architecture
+
+### Coexistence des deux chemins d'auth sur `/_mcp`
+
+| Chemin | Clients | Mécanisme |
+| ---------------------------------------------- | ----------------------------------------- | ---------------------------------------------------------- |
+| Jeton statique `colibre_…` (scope B, inchangé) | Claude Code, Gemini, Mistral | collé à la main depuis `/compte/mcp` |
+| **OAuth 2.1 (ce scope B2)** | Claude.ai, Claude Desktop/mobile, ChatGPT | « Ajouter un connecteur » → flux OAuth, zéro copier-coller |
+
+### Arborescence
+
+```
+src/mcp/oauth/
+ __init__.py
+ store.py # stores sqlite bruts : clients (DCR), codes, tokens
+ server.py # authlib AuthorizationServer : AuthorizationCodeGrant+PKCE, RefreshTokenGrant, DCR
+ metadata.py # documents JSON RFC 9728 (protected-resource) + RFC 8414 (AS)
+ consent.py # écran de consentement + gate abonnement
+ routes.py # blueprint Flask : /.well-known/*, /oauth/register, /oauth/authorize, /oauth/token, /oauth/revoke
+src/mcp/usage.py # journal d'usage /_mcp (niveau 1 détection)
+```
+
+Fichiers **modifiés** : `src/mcp/auth.py` (garde `/_mcp` accepte aussi les tokens
+OAuth + en-tête `resource_metadata` + journal `mcp_usage`), `src/migrations.py`
+(nouvelles tables), `src/pages/compte/mcp.py` (instructions Claude.ai / ChatGPT),
+`src/app.py` (enregistrement blueprint + exemption CSRF).
+
+### Isolation des unités
+
+- `store.py` : accès sqlite pur (clients/codes/tokens), testable sans HTTP ni authlib.
+- `server.py` : configuration authlib (grants, hooks `query_client`/`save_token`),
+ branchée sur `store.py`.
+- `metadata.py` : documents JSON purs (fonctions déterministes de `APP_BASE_URL`).
+- `consent.py` : rendu de l'écran + gate abonnement, testable indépendamment.
+- `usage.py` : journal `/_mcp`, testable isolément.
+
+## Stockage — 3 tables OAuth + 1 table usage (`users.sqlite`)
+
+Créées via `_MIGRATIONS` et initialisées au démarrage (`init_schema`, comme
+`tokens_db`), **avant** `apply_pending()`. Tolérance _duplicate_ déjà gérée.
+
+- **`oauth_clients`** — `client_id` (PK), `client_metadata` (JSON : `redirect_uris`,
+ `client_name`, `token_endpoint_auth_method='none'`, `grant_types`, `scope`),
+ `created_at`. Clients **publics**, créés par DCR.
+- **`oauth_codes`** — `code_hash` (PK), `client_id`, `user_id`, `redirect_uri`,
+ `code_challenge`, `code_challenge_method`, `scope`, `resource`, `expires_at`,
+ `used`. Éphémère (~60 s).
+- **`oauth_tokens`** — `access_token_hash`, `refresh_token_hash`, `client_id`,
+ `user_id`, `scope`, `resource` (audience), `issued_at`, `access_expires_at`
+ (+1 h), `refresh_expires_at` (+60 j), `revoked_at`. Rotation du refresh à chaque
+ usage.
+- **`mcp_usage`** — `id` (PK), `user_id`, `token_id`, `kind` (`'static'`|`'oauth'`),
+ `created_at`. Une ligne par requête `/_mcp` **authentifiée** (niveau 1 détection).
+
+Les jetons statiques restent dans `api_tokens` (inchangé).
+
+## Endpoints, discovery & flux OAuth
+
+Blueprint `src/mcp/oauth/routes.py` sur `app.server`, **exempté de CSRF** (comme
+`/_mcp` ; POST externes sans jeton CSRF).
+
+| Route | Méthode | Rôle |
+| ------------------------------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `/.well-known/oauth-protected-resource` + `…/oauth-protected-resource/_mcp` | GET | **PRM (RFC 9728)** : `{ resource:"/_mcp", authorization_servers:[issuer], scopes_supported:["mcp","offline_access"] }` |
+| `/.well-known/oauth-authorization-server` + `/.well-known/openid-configuration` | GET | **AS metadata (RFC 8414)** : `authorization_endpoint`, `token_endpoint`, `registration_endpoint`, `code_challenge_methods_supported:["S256"]`, `token_endpoint_auth_methods_supported:["none"]`, `grant_types_supported:["authorization_code","refresh_token"]`, `scopes_supported:["mcp","offline_access"]`, `issuer` |
+| `/oauth/register` | POST (JSON) | **DCR (RFC 7591)** : crée un `oauth_clients` public, renvoie `client_id` + metadata |
+| `/oauth/authorize` | GET / POST | **Consentement** : login flask_login → gate abonnement → écran → code |
+| `/oauth/token` | POST (form) | grants `authorization_code` (+PKCE) et `refresh_token` (rotation) |
+| `/oauth/revoke` | POST (form) | **RFC 7009** (révocation ; peu coûteux) |
+
+### Flux `/authorize`
+
+1. `server.get_consent_grant()` (authlib) valide `client_id`, `redirect_uri`
+ (exact-match), `resource`, `code_challenge`.
+2. `current_user` non authentifié → `redirect('/connexion?next=')`,
+ retour ici après login.
+3. Connecté mais **pas d'abonnement actif** (`TOUS_ABONNES or has_active_subscription(user_id)` faux) → page HTML « Abonnement requis » + lien
+ `/compte/abonnement`, **aucun code émis**.
+4. Sinon → écran de consentement minimal : nom du client, **hostname du
+ redirect_uri**, périmètre (« lire les données colibre en votre nom »),
+ boutons Autoriser / Refuser.
+5. **Autoriser** → `server.create_authorization_response(grant_user=current_user)` :
+ `code_hash` stocké dans `oauth_codes` (avec `resource`, `code_challenge`),
+ redirection vers le client.
+
+### Flux `/token`
+
+- `authorization_code` : authlib échange code + `code_verifier` (PKCE S256) →
+ `oauth_tokens` (access 1 h, refresh 60 j, `resource` copié comme audience).
+ Code invalide / `code_verifier` erroné → `invalid_grant`.
+- `refresh_token` : **rotation** (ancien refresh révoqué, nouveau renvoyé dans la
+ même réponse), et **re-vérification de l'abonnement** : si perdu → `invalid_grant`,
+ ce qui force le client à relancer le flux complet (lequel rebute au gate
+ `/authorize`).
+
+## Garde `/_mcp` unifié (`src/mcp/auth.py`)
+
+1. **401 enrichi** :
+ `WWW-Authenticate: Bearer realm="colibre-mcp", resource_metadata="/.well-known/oauth-protected-resource/_mcp"`.
+2. **Routage du Bearer** :
+ - préfixe `colibre_` → chemin statique existant (`api_tokens`, inchangé) ;
+ - sinon → chemin OAuth (`oauth_tokens` : lookup haché, **non expiré**,
+ **audience == `/_mcp`**, non révoqué).
+3. Convergence : `user_id` → abonnement actif → `increment_usage` →
+ **`mcp_usage.record(user_id, token_id, kind)`** (best-effort) → laisser passer.
+4. Échecs : token invalide / expiré / mauvaise audience / révoqué → **401** (avec
+ le header) ; `user_id` nul ou abonnement inactif → **403**. Rien n'est journalisé
+ dans `mcp_usage` sur échec.
+
+## Abonnement : sémantique `TOUS_ABONNES` et « pas de droit acquis »
+
+`TOUS_ABONNES` est lu au démarrage (constante d'`os.getenv`). L'abonnement est
+**re-vérifié à chaque requête** `/_mcp`, pas seulement à l'émission du token :
+
+| Moment | Effet sur un token OAuth existant |
+| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `TOUS_ABONNES=true` | Tout utilisateur connecté franchit `/authorize`, obtient un token ; chaque requête `/_mcp` passe. |
+| `TOUS_ABONNES` → `false` (après redémarrage) | Token ni supprimé ni révoqué, mais à la requête suivante le garde ré-évalue `False or has_active_subscription(user_id)`. Sans abonnement actif → **403** immédiat ; le token devient inerte. |
+| L'utilisateur s'abonne ensuite | Le **même** token refonctionne (garde de nouveau vrai), sans re-login. |
+
+Il n'existe **aucune fenêtre de tolérance** : le check étant par requête, même un
+token émis juste avant le basculement est bloqué dès l'appel suivant. Cohérent avec
+le refresh (`invalid_grant` si abonnement perdu).
+
+## Détection d'usage — niveau 1 (`src/mcp/usage.py`)
+
+Objectif : rendre l'usage `/_mcp` **interrogeable** (socle d'un futur quota /
+rate-limiting), sans encore plafonner.
+
+- **`record(db_path, user_id, token_id, kind)`** : insère `(user_id, token_id, kind, created_at)` dans `mcp_usage`. Appelé par le garde après un succès. **Best-effort**
+ (jamais bloquant).
+- **`count_since(db_path, user_id, iso_ts) -> int`** : nombre de requêtes d'un
+ utilisateur depuis un horodatage (base d'un futur seuil/minute).
+- **`purge_older_than(db_path, days=90)`** : suppression des lignes anciennes,
+ appelée **au démarrage** (mirror de `db.purge_expired_tokens()`), pour borner la
+ croissance.
+
+Signaux de détection disponibles **au total** après ce scope :
+
+- **Matomo** (déjà câblé, scope A) : volume par tool dans le temps (anonyme).
+- **Compteurs par token** : `count_total` / `last_used_at` (`api_tokens` +
+ `oauth_tokens`), cumulatifs.
+- **`mcp_usage`** : journal par requête, fenêtrable par utilisateur.
+- **Logs d'accès** gunicorn/nginx : brut, par IP.
+
+## UI `/compte/mcp` (`src/pages/compte/mcp.py`)
+
+La page conserve son générateur de jetons statiques ; l'accordéon `client_instructions`
+évolue :
+
+- **Claude Code / Gemini / Mistral** : inchangés (jeton statique collé).
+- **Claude.ai / Desktop / mobile** : nouvelle entrée « Aucun jeton à copier » →
+ _Paramètres → Connecteurs → Ajouter un connecteur personnalisé → URL
+ `https://colibre.fr/_mcp` → se connecter avec colibre → Autoriser_. Champ
+ « Client Secret » laissé vide (client public).
+- **ChatGPT** : remplace le texte « votez pour la fonctionnalité » par les étapes
+ réelles (connecteurs → ajouter par URL `https://colibre.fr/_mcp` → flux OAuth) ;
+ note que la disponibilité dépend du plan ChatGPT de l'utilisateur.
+- Court paragraphe expliquant : **jeton = clients CLI**, **OAuth = apps grand
+ public**, même abonnement requis.
+
+Les tokens OAuth (éphémères, gérés par le client) ne sont **pas** listés dans le
+tableau, qui reste réservé aux jetons statiques.
+
+## Activation & configuration
+
+- Toujours piloté par **`DASH_MCP_ENABLED=true`** (le flux OAuth ne s'enregistre que
+ dans ce bloc de `app.py`, après `configure_mcp_server`).
+- **`APP_BASE_URL`** sert d'**issuer** et à construire `resource` / URLs well-known.
+ **HTTPS obligatoire** hors dev (exigence spec) ; localhost toléré en dev.
+- **Aucun nouveau secret** (tokens opaques hachés ; `SECRET_KEY` déjà présent).
+- `.template.env` : documenter que le flux OAuth requiert `APP_BASE_URL` en HTTPS et
+ que l'egress Anthropic `160.79.104.0/21` doit être joignable.
+- Déploiement recommandé : activer d'abord sur `test.colibre.fr` (branche `dev`),
+ valider un connecteur Claude.ai réel, puis `main`.
+
+## Stratégie de test
+
+- **`tests/mcp/test_oauth_metadata.py`** : PRM (`resource` exact, `authorization_servers`,
+ `scopes_supported` inclut `offline_access`) ; AS metadata
+ (`code_challenge_methods_supported:["S256"]`, `none`, `registration_endpoint`,
+ grants) ; `/.well-known/openid-configuration` = miroir ; variantes suffixées `/_mcp`.
+- **`tests/mcp/test_oauth_store.py`** : CRUD clients/codes/tokens, hachage,
+ expiration, rotation refresh, révocation.
+- **`tests/mcp/test_oauth_flow.py`** : DCR → client public ; `/authorize`
+ (non connecté → redirection ; connecté sans abonnement → « Abonnement requis »,
+ **aucun code** ; avec abonnement → code) ; `/token` avec PKCE S256 (mauvais
+ `code_verifier` → `invalid_grant`) ; `resource`/audience copiée ; redirect_uri
+ non enregistrée → rejet.
+- **`tests/mcp/test_auth.py`** (étendre) : garde accepte un token OAuth valide ;
+ rejette expiré / mauvaise audience / révoqué (**401 + `resource_metadata`**) ;
+ **`TOUS_ABONNES=false` + pas d'abonnement → 403 même avec token OAuth valide** ;
+ refresh refusé (`invalid_grant`) si abonnement perdu.
+- **`tests/mcp/test_usage.py`** (nouveau) : `record` insère sur succès ; **aucune
+ insertion sur 401/403** ; fenêtrage de `count_since` ; `purge_older_than`.
+- **Migration** : `apply_pending()` idempotente (DB existante → ajoute les tables ;
+ DB fraîche → tolère _duplicate_).
+
+## Hors-périmètre (YAGNI → itérations futures)
+
+- **CIMD** (Client ID Metadata Document, spec MCP 2025-11-25) et redirect loopback
+ port-agnostic (Claude Code passe déjà par jeton statique).
+- `oauth_anthropic_creds`, `private_key_jwt`, mTLS, `id_token_hint`, tokens JWT/JWKS.
+- **Rate-limiting / quotas / 429 / alerting** (niveaux 2-3) : `mcp_usage` en pose le
+ socle, le plafonnement effectif fera l'objet d'une issue dédiée.
+- Scopes fins par tool ; écran de gestion/révocation des connexions OAuth actives
+ côté utilisateur.
+- Soumission au directory de connecteurs Claude / ChatGPT.