Connecter Claude ou ChatGPT à vos avis

Ce que vous obtenez

« Que disent mes clients de mes desserts ce mois-ci ? » Votre assistant IA va chercher la réponse dans vos avis, sans export ni copier-coller : il liste les avis de la période, les lit et vous en fait la synthèse.

Le lien passe par le serveur MCP de l'API, à l'adresse https://api.mabellenote.com/v1/mcp. MCP (Model Context Protocol) est un protocole ouvert qui permet à un assistant IA d'appeler des outils. La page Assistant IA présente les usages ; ce guide détaille la connexion.

Deux façons de se connecter :

• Par OAuth, recommandé : vous collez l'adresse du serveur dans l'assistant, une fenêtre Ma Belle Note s'ouvre, vous choisissez le compte et les droits, et c'est prêt. Aucune clé à copier. C'est le mode de claude.ai, de ChatGPT, de Le Chat, de Claude Code, de Cursor et de tout client MCP qui gère OAuth.
• Par clé API, en mode avancé : pour un serveur, une automatisation ou un client MCP sans OAuth, une clé mbn_live_ s'envoie dans l'en-tête Authorization. Voir la connexion par clé API.

Il vous faut

• Un compte Ma Belle Note au plan Pro, ou en essai gratuit : l'API y est incluse.
• Un accès propriétaire ou administrateur (permission de gérer l'API), pour autoriser la connexion.
• Un assistant qui accepte les connecteurs MCP personnalisés. Selon l'éditeur, cette option peut dépendre de votre offre.

1. Ajouter le serveur dans votre assistant

L'adresse à coller est la même partout :

https://api.mabellenote.com/v1/mcp

Claude (claude.ai et applications)

Sur claude.ai, ouvrez Paramètres › Connecteurs, puis Ajouter un connecteur personnalisé. Nommez-le Ma Belle Note, collez l'adresse du serveur et validez, puis cliquez sur Se connecter. Le connecteur se retrouve ensuite dans les applications Claude pour ordinateur et mobile. Dans une organisation, l'ajout peut être réservé à son administrateur.

ChatGPT

ChatGPT n'accepte un connecteur ajouté par son adresse qu'en mode développeur. Dans les paramètres de ChatGPT, section des applications et connecteurs, ouvrez les paramètres avancés et activez le mode développeur. Créez ensuite un connecteur, nommez-le Ma Belle Note, collez l'adresse du serveur et choisissez l'authentification OAuth. Dans une conversation, activez le connecteur depuis le menu des outils.

Le Chat, Grok, Perplexity

Ouvrez la gestion des connecteurs de l'assistant (dans Le Chat : Intelligence › Connecteurs), ajoutez un connecteur MCP personnalisé et collez l'adresse du serveur. Si l'option n'apparaît pas, elle n'est pas proposée par votre offre ou votre application.

Claude Code

Une commande suffit, sans en-tête ni clé :

claude mcp add --transport http ma-belle-note https://api.mabellenote.com/v1/mcp

Au premier usage, tapez /mcp dans Claude Code, choisissez ma-belle-note puis la connexion : votre navigateur ouvre la fenêtre Ma Belle Note. Par défaut, le serveur n'est disponible que dans le projet où vous avez lancé la commande : ajoutez --scope user pour l'utiliser dans tous vos projets.

Cursor

Ajoutez le serveur dans .cursor/mcp.json (projet) ou ~/.cursor/mcp.json (tous vos projets) :

{
  "mcpServers": {
    "ma-belle-note": {
      "url": "https://api.mabellenote.com/v1/mcp"
    }
  }
}

Dans les réglages MCP de Cursor, lancez ensuite la connexion du serveur.

Autres clients MCP

Tout client qui parle le transport HTTP de MCP et gère l'autorisation OAuth 2.1 de la spécification MCP peut se connecter avec la seule adresse. Le serveur répond 401 avec un en-tête WWW-Authenticate qui pointe vers ses métadonnées (RFC 9728) ; le client y découvre le serveur d'autorisation (RFC 8414), s'inscrit (document de métadonnées client, ou inscription dynamique RFC 7591), puis ouvre la fenêtre de connexion avec PKCE S256 et le paramètre resource.

2. Autoriser la connexion

Une fenêtre Ma Belle Note s'ouvre dans votre navigateur :

1. Connectez-vous avec votre compte habituel, si ce n'est pas déjà fait.
2. Choisissez le compte à relier. Seuls apparaissent les comptes où vous êtes propriétaire ou administrateur et dont le plan inclut l'API.
3. Choisissez les droits, avec les mêmes modèles qu'à la création d'une clé. Lecture seule est proposé par défaut : il donne la lecture des établissements, des avis, des statistiques et des retours privés, sans accès à votre base clients. Pour que l'assistant prépare aussi des réponses, cochez en plus Rédiger des réponses avec l'IA (ai:generate).
4. Cliquez sur Autoriser. Vous revenez dans l'assistant, connecté.

La fenêtre signale un client non vérifié, et s'arrête avec un message clair si aucun compte n'est éligible ou si le compte a déjà ses 10 clés.

Une connexion est une clé API du compte, d'origine OAuth : elle apparaît dans Réglages › Intégration, API & webhooks avec le badge Assistant IA, le nom de l'assistant et sa dernière utilisation. Elle compte parmi les 10 clés du compte, et un email signale sa création. Il n'y a ni secret à afficher, ni rotation à prévoir : l'assistant renouvelle seul sa connexion.

3. Poser vos questions

Parlez à l'assistant comme à un collègue qui aurait accès à vos avis. Il choisit lui-même les outils et leurs filtres :

• « Que disent mes clients de mes desserts ce mois-ci ? »
• « Quels avis négatifs sont encore sans réponse ce mois-ci ? »
• « Résume les retours privés de la semaine. »
• « Compare la note moyenne de mes établissements sur les trois derniers mois. »
• « Prépare une réponse à cet avis. »

Pour la deuxième question, par exemple, il peut appeler list_reviews pour les notes de 1 et 2 étoiles, sans réponse publiée, depuis le premier du mois. Pour la dernière, il lui faut le droit ai:generate : le brouillon apparaît ensuite dans l'application, où vous le relisez avant de le publier.

Les outils de l'assistant

Le serveur expose 19 outils, mais l'assistant ne voit que ceux permis par les droits de la connexion : un outil hors droits n'apparaît pas dans sa liste.

Les outils de lecture ne modifient rien. Avec le droit replies:write ou ai:generate, get_review et list_reviews montrent aussi le brouillon en cours (draft) : l'assistant peut relire et ajuster le brouillon qu'il vient de préparer. Chaque outil d'écriture est signalé comme tel à l'assistant, qui vous demande votre accord avant de l'utiliser. Les écritures restent dans Ma Belle Note, sauf publish_reply, qui publie la réponse sur Google, et seulement pour un établissement qui a autorisé la publication par l'API (voir la publication sur Google). draft_reply et save_reply_draft créent un brouillon dans l'application, sans rien publier sur Google : la réponse attend votre validation, comme tout brouillon. draft_reply consomme une unité du crédit IA mensuel du compte. Les outils d'écriture et d'événements s'appuient sur des opérations encore en bêta, décrites dans le guide des écritures et le guide des webhooks.

Déconnecter l'assistant

La connexion se coupe des deux côtés, avec effet immédiat :

• Dans l'assistant : retirez le connecteur de ses réglages, ou lancez claude mcp remove ma-belle-note dans Claude Code. Quand l'assistant signale la déconnexion au serveur (révocation RFC 7009), la clé est révoquée aussitôt ; pour en être certain, révoquez-la aussi dans Ma Belle Note.
• Dans Ma Belle Note : révoquez la clé Assistant IA dans Réglages › Intégration, API & webhooks. L'appel suivant de l'assistant échoue, et il faut l'autoriser à nouveau pour le rebrancher.

Connexion par clé API (mode avancé)

Pour un serveur, une automatisation ou un client MCP qui n'accepte pas OAuth, le serveur accepte aussi une clé API dans l'en-tête Authorization, comme le reste de l'API.

Créez une clé dédiée dans Réglages › Intégration, API & webhooks, avec le modèle Lecture seule, et nommez-la d'après son usage. La clé commence par mbn_live_ et ne s'affiche qu'une seule fois. Dans les exemples, remplacez mbn_live_... par votre clé. Le paramètre lang choisit la langue des descriptions des outils : fr pour le français, en pour l'anglais, qui s'applique aussi sans paramètre.

Avec Claude Code :

claude mcp add --transport http ma-belle-note "https://api.mabellenote.com/v1/mcp?lang=fr" \
  --header "Authorization: Bearer mbn_live_..."

Avec un client qui ne sait lancer que des serveurs locaux, le relais mcp-remote (lancé avec npx, il demande Node.js) transmet l'en-tête :

{
  "mcpServers": {
    "ma-belle-note": {
      "command": "npx",
      "args": ["mcp-remote", "https://api.mabellenote.com/v1/mcp?lang=fr", "--header", "Authorization:${AUTH}"],
      "env": {
        "AUTH": "Bearer mbn_live_..."
      }
    }
  }
}

L'en-tête s'écrit sans espace après les deux-points et la clé passe par la variable AUTH : certains systèmes coupent les arguments qui contiennent une espace.

Le serveur refuse les appels envoyés depuis une page web : la clé reste sur votre ordinateur ou sur votre serveur. Une clé enregistrée dans la configuration d'un poste se révoque dans l'application si le poste est perdu ou partagé.

Limites

• Débit : l'assistant partage la limite de sa clé, 120 appels par minute. Chaque échange avec le serveur compte pour un appel, y compris la liste des outils, et draft_reply compte pour 5. Une question large peut demander plusieurs appels, pour parcourir plusieurs pages d'avis. Au-delà de la limite, l'outil répond 429 rate_limited : le guide des limites détaille le fonctionnement.
• Crédit IA : chaque brouillon demandé par draft_reply consomme une unité du crédit IA mensuel, comme dans l'application. À crédit épuisé, l'outil répond 402 ai_credits_exhausted. Sur un compte en lecture seule, par exemple après la fin de l'essai, il répond 403 tenant_read_only.
• Journal des appels : chaque appel de l'assistant figure pendant 14 jours dans Réglages › Intégration, API & webhooks, onglet Consommation, avec la clé, l'opération, le statut et la durée. Un appel d'outil porte le nom de l'opération qu'il utilise, par exemple v1 · reviews.list, et les autres échanges v1 · mcp.protocol.

Ce qu'il faut savoir

• Vos données passent par l'assistant : les avis, les noms de leurs auteurs et les retours privés que l'assistant lit sont transmis à l'éditeur de l'assistant, qui les traite selon ses propres conditions. Ne donnez à la connexion que les droits utiles, par exemple sans feedbacks:read si vos retours privés doivent rester dans l'application.
• Tous vos établissements : une connexion couvre tous les établissements du compte, présents et futurs.
• L'assistant peut se tromper : il résume et interprète. Les chiffres de référence restent ceux de l'application.
• Rien n'est publié sans le droit de publier : sans replies:publish, aucun outil ne publie sur Google, et la publication d'une réponse se fait dans l'application. Avec ce droit, publish_reply ne publie que pour les établissements qui ont autorisé la publication par l'API, et l'assistant vous demande votre accord avant chaque publication.