Le MCP Mentionable utilise une authentification par bearer token avec des API keys scopées sur le workspace. Il y a deux façons d'obtenir un token : coller une API key statique (idéal pour Claude Desktop, Cursor, n8n, scripts), ou se connecter via OAuth (pour les connecteurs hébergés comme ChatGPT et Claude qui n'exposent qu'un bouton Connect). Les deux résolvent la même clé mnt_sk_ en coulisses, donc tout ce qui suit (scopes, rôles, rate limits) s'applique aux deux.

Tutoriel vidéo

Comment créer une clé API Mentionable et la brancher à Claude ou ChatGPT.

Comment fonctionne l'authentification ?

Chaque requête envoie un bearer token dans le header Authorization. Le token commence par mnt_sk_, est haché côté serveur en SHA-256, et résout un membre du workspace avec ses permissions scopées par projet. Le token est vérifié, le rate limit est checké, le tool est dispatché.

Les API keys

Les API keys Mentionable se créent et se gèrent dans Settings → API Keys (MCP) sur mentionable.ai.

Propriété	Valeur
Préfixe	`mnt_sk_`
Partie aléatoire	32 caractères base64url
Stockage	Hash SHA-256 uniquement, le plaintext n'apparaît qu'une fois
Propriété	Liée à un membre du workspace
Scope	Hérite du membre, optionnellement restreint à des projets
`lastUsedAt`	Mis à jour à chaque appel réussi

Envoyer le token

Deux transports acceptés, dans cet ordre :

Header Authorization (recommandé) :
```
Authorization: Bearer mnt_sk_xxx
```
Paramètre query (pour les clients qui ne peuvent pas définir de header, certains outils webhook par exemple) :
```
POST https://mentionable.ai/api/mcp?key=mnt_sk_xxx
```
Le nom apiKey est aussi accepté. À éviter quand vous pouvez, les query strings finissent dans les logs serveur.

Se connecter en OAuth (connecteurs ChatGPT et Claude)

Les connecteurs hébergés, comme les connecteurs ChatGPT et les connecteurs custom de Claude, n'acceptent pas une API key collée à la main. Ils attendent un flow OAuth 2.1 derrière un bouton Connect. Mentionable le supporte nativement : vous ne copiez jamais de token.

Comment se connecter

Dans la configuration du connecteur, ajoutez un serveur MCP custom avec l'URL https://mentionable.ai/api/mcp.
Cliquez sur Connect. Le connecteur découvre le serveur d'autorisation et ouvre un écran de consentement Mentionable.
Connectez-vous à mentionable.ai si ce n'est pas déjà fait, puis cliquez sur Approve.
C'est tout. Le connecteur est authentifié. Aucun token à copier ni à stocker.

Gérer les connexions OAuth

Chaque connecteur que vous approuvez apparaît dans Settings → API Keys (MCP) sous le nom MCP OAuth (host), par exemple MCP OAuth (claude.ai). Pour déconnecter un connecteur, révoquez cette clé. Les access tokens OAuth n'expirent pas d'eux-mêmes : la révocation est le moyen de couper l'accès.

OAuth, comme les clés statiques, nécessite le plan Pro ou Agency. Un workspace Growth (ou inférieur) reçoit access_denied quand le connecteur tente d'obtenir un token.

Quel mode choisir ?

Client	Auth recommandée
Connecteurs ChatGPT, connecteurs custom Claude web	OAuth (le bouton Connect)
Claude Desktop, Cursor, VS Code	API key statique collée en bearer token
n8n, cron jobs, scripts custom	API key statique (header ou query param)

Les clés statiques sont plus simples pour tout ce qui lit un fichier de config ou une variable d'environnement. OAuth est fait pour l'expérience « Connect » hébergée où coller un token n'est pas une option.

Scopes de projet

Le scope effectif est l'intersection de deux couches :

Couche	Liste vide veut dire	Liste non-vide veut dire
Scope du membre du workspace	Accès à tous les projets du tenant	Whitelist d'IDs de projets
Scope de l'API key	Hérite du scope du membre	Restreint à certains IDs de projets

Un appel sur un projet hors du scope effectif retourne :

{ "error": { "code": "FORBIDDEN", "message": "Project not in API key scope" } }

Les tools d'écriture (bulk_update_competitor_status) exigent en plus que le rôle du membre soit au moins member. Le rôle customer est read-only et ne peut pas modifier le statut d'un concurrent.

Rate limits

Le MCP Mentionable applique un rate limit de 100 requêtes par 60 secondes par API key, en sliding window via Redis.

Quand le rate limit est atteint :

HTTP/1.1 429 Too Many Requests
Retry-After: 17
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1714128037

La pagination compte une requête par page. Une boucle qui parcourt 200 prompts à limit: 20 représente 10 requêtes. Prévoyez du backoff si vous orchestrez beaucoup d'appels depuis une seule clé.

Révoquer une clé

Ouvrez Settings → API Keys (MCP), retrouvez la clé par son préfixe et sa date de création, cliquez sur Revoke. Tout client utilisant la clé reçoit 401 dès l'appel suivant. C'est immédiat et irréversible.

Pour faire tourner les clés :

Émettez une nouvelle clé.
Mettez à jour la config du client (Claude Desktop, Cursor, n8n).
Vérifiez avec un appel tools/list que la nouvelle clé fonctionne.
Révoquez l'ancienne.

Bonnes pratiques

Une clé par client. Ne partagez pas claude-desktop entre plusieurs personnes.
Nommez les clés selon leur consommateur : n8n-rapport-mensuel, cursor-alex, gha-cron-veille.
Restreignez la clé à un seul projet quand le consommateur n'en a besoin que d'un.
Faites tourner les clés tous les trimestres. Révoquez l'ancienne après avoir branché la nouvelle.
Ne committez jamais une clé dans Git. Utilisez des variables d'environnement ou le secret store de votre client.

Ce qu'une API key ne peut PAS faire

Créer ou supprimer des projets.
Modifier le billing ou l'abonnement.
Lire les données d'un autre workspace.
Contourner le scope projets du membre.

Le MCP Mentionable est principalement en lecture. Aujourd'hui, trois tools d'écriture sont exposés : bulk_update_competitor_status (tri des concurrents suggérés), bulk_update_reddit_thread_status (tri des threads Reddit) et enrich_reddit_thread (déclencher un scrape Bright Data, consomme des credits). Les nouveaux tools d'écriture sont annoncés via les release notes produit régulières.