Authentification

Le MCP Mentionable utilise une authentification par bearer token avec des API keys scopées sur le workspace.

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.

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 crédits IA). Les nouveaux tools d'écriture sont annoncés via les release notes produit régulières.