Connecter Claude à HubSpot : les 3 méthodes et leurs limites réelles

Depuis le 13 avril 2026, le serveur MCP distant de HubSpot est en version stable et il sait écrire dans le CRM. Contacts, entreprises, transactions, tickets, activités : un modèle de langage peut créer et modifier des enregistrements de production, avec les droits de l'utilisateur qui a autorisé la connexion. La bascule est passée assez discrètement dans le changelog développeur.

Résultat : beaucoup d'équipes ont aujourd'hui une connexion active entre Claude et HubSpot sans savoir lequel des trois chemins possibles elles ont emprunté, ni quel périmètre elles ont ouvert. Connecter Claude à HubSpot recouvre en effet trois montages distincts. Voici leur périmètre réel, leurs limites, et les cinq usages par lesquels commencer.

Claude connecté au CRM et Breeze : deux sujets distincts

Breeze est l'IA de HubSpot, à l'intérieur du produit, avec un périmètre et une facturation contrôlés par l'éditeur. Nous l'avons détaillée dans notre article sur Agent Hub et le pilotage des agents IA HubSpot.

Claude connecté à HubSpot fonctionne dans l'autre sens : un assistant extérieur au portail obtient un accès à la donnée. Les enregistrements de référence restent dans HubSpot, et les données appelées transitent vers le modèle le temps de produire la réponse. Le protocole qui rend cet échange possible s'appelle MCP, pour Model Context Protocol : une interface standardisée par laquelle un modèle demande des informations à une application et déclenche des actions chez elle.

HubSpot parle de passerelle sécurisée. C'est exact, à condition de préciser que la sécurité repose entièrement sur les droits accordés à la connexion. Les deux briques cohabitent sans conflit sur un même portail. Leur différence tient au niveau de contrainte : HubSpot borne le périmètre d'action de Breeze, alors qu'une connexion MCP expose un ensemble d'objets à un modèle généraliste dépourvu de garde-fou métier.

Les trois méthodes de connexion

Une seule question les distingue vraiment : au nom de qui la connexion agit, et qui fait tourner le programme qui la porte.

Les deux premières lignes reposent sur le même moteur : le connecteur est le serveur distant avec une installation en un clic. La troisième change l'identité qui porte la connexion, et c'est de là que vient tout l'écart de gouvernance.

1. Le connecteur HubSpot dans Claude

Premier connecteur CRM publié pour Claude, annoncé le 29 juillet 2025. Installation en deux minutes côté Claude, aucune configuration. Toutes les éditions HubSpot y sont éligibles ; côté Claude, il faut un abonnement payant (Pro, Max, Team ou Enterprise).

L'usage visé est conversationnel : interroger son pipeline en langage naturel, obtenir une analyse ou une visualisation, déclencher une action. Deux points reviennent systématiquement en comité sécurité. Un utilisateur n'accède qu'aux données qu'il peut déjà voir dans HubSpot. Et le contenu brut remonté par un connecteur n'entre pas dans l'entraînement des modèles Anthropic : sur les offres grand public, seules les conversations elles-mêmes peuvent l'être, si l'utilisateur a activé l'option d'amélioration du modèle, avec une exception pour les échanges signalés par une revue de sécurité. Ces conditions ont évolué plusieurs fois depuis 2025 : à revérifier pour le plan souscrit plutôt qu'à reprendre d'un article.

C'est la méthode adaptée quand la demande vient du marketing ou du commerce et porte sur l'analyse plutôt que sur l'action.

2. Le serveur MCP distant

Le socle technique, hébergé par HubSpot sur https://mcp.hubspot.com. En version stable depuis le 13 avril 2026, avec l'ajout à cette occasion de l'écriture, de l'historique d'activité, des objets de contenu marketing et du contexte organisationnel. Tout client compatible MCP gérant OAuth avec PKCE peut s'y connecter : Claude Desktop, Claude Code, Cursor.

Le périmètre ne suit aucune logique intuitive, d'où ce tableau, à lire avant d'autoriser une connexion.

Une exclusion mérite l'attention : sur un portail où la fonctionnalité de données sensibles est activée, les objets d'activité sont bloqués côté serveur MCP. Restriction propre au MCP, absente des API CRM standard. Une équipe qui a construit un usage sur la lecture des appels et des notes peut donc le voir disparaître le jour où le portail active les données sensibles pour un tout autre besoin.

L'authentification a changé au passage en version stable. OAuth 2.1 avec PKCE est désormais obligatoire, via une application d'authentification créée dans le portail sous Development > MCP Auth Apps (chemins de menus donnés dans l'interface anglaise), section ouverte en libre-service le 13 janvier 2026. Les connexions antérieures basculent en statut REQUIRES_REAUTHORIZATION et doivent être reconnectées. Ce détail explique une bonne part des « ça marchait la semaine dernière » du printemps 2026.

Point structurant pour la suite : sur cette méthode, vous ne choisissez pas les portées. Elles sont celles du rôle de l'utilisateur qui autorise la connexion, ni plus ni moins.

3. Le serveur auto-hébergé avec un jeton de service

C'est la méthode la moins documentée des trois, et la seule qui permette de définir un périmètre portée par portée, plus étroit que n'importe quel rôle HubSpot.

Vous faites tourner un serveur MCP que vous contrôlez, en général le paquet npm communautaire mcp-hubspot, open source et donc auditable. L'authentification passe par un jeton de service, créé sous Development > Keys > Service keys : un identifiant de compte à compte, sans application ni OAuth. Les portées se cochent une par une et restent modifiables après création. La combinaison crm.objects.deals.read sans crm.objects.deals.write est inaccessible aux deux premières méthodes ; elle se coche ici dans l'écran des portées.

Trois éléments de son fonctionnement comptent pour la gouvernance. La rotation du jeton, avec sept jours de grâce ou une expiration immédiate en cas de compromission. Le journal des requêtes récentes et la date de dernière utilisation, consultables depuis la fiche du jeton. Et une contrainte à connaître avant de promettre un périmètre à une équipe : un créateur ne peut pas accorder une portée qu'il ne possède pas lui-même, le moindre privilège se construisant donc vers le bas.

Deux limites. Les jetons de service ne gèrent ni les webhooks ni les extensions d'interface, qui relèvent des apps projet. Et la fonctionnalité est en bêta publique depuis février 2026, donc à vérifier avant de bâtir dessus.

Quatre usages qu'elle rend possibles et que les autres ne couvrent pas :

• Les agents qui tournent sans personne devant l'écran : enrichissement nocturne, synthèse de pipeline postée à 8h, détection de transactions dormantes. Un flux OAuth interactif suppose quelqu'un pour cliquer un écran de consentement, ce qui exclut par construction toute tâche planifiée et tout scénario n8n. Aucune des deux autres méthodes ne couvre ce cas.
• Un jeton par usage, révocable seul : lecture des transactions pour le reporting, écriture d'activités pour la journalisation, un jeton de chantier révoqué le chantier terminé. Cette granularité n'existe pas quand le périmètre est celui d'une session utilisateur.
• La réduction de la surface d'outils, et pas seulement des portées : retirer les outils d'écriture du serveur lui-même. Une portée absente bloque l'action au moment de l'appel ; un outil retiré ne figure pas dans les options que le modèle peut envisager.
• La traçabilité : les jetons de service exposent nativement les requêtes récentes et la date de dernière utilisation, et le serveur que vous exploitez peut journaliser le reste (outil appelé, enregistrements touchés).

Le prix à payer est réel. Hébergement, mises à jour et audit du code à votre charge, aucun support HubSpot sur un paquet communautaire, et un secret de production à faire tourner. Les modifications apparaissent au nom du jeton et non d'un utilisateur nommé, ce qui complique la relecture de l'historique d'une fiche.

Une précision pour éviter un contresens fréquent : pour un besoin industrialisé et stable, appeler directement les API HubSpot avec le même jeton reste souvent plus simple qu'un serveur MCP intermédiaire. Le MCP prend son intérêt quand c'est un modèle qui décide de l'appel, pas votre code.

Choisir la méthode qui vous convient

Le choix se joue sur trois besoins distincts. Avec un préalable qui ne relève pas du branchement : un portail dont les objets, les propriétés et les pipelines sont déjà structurés, ce qui est le sujet d'un chantier d'intégration CRM et se traite en amont.

Deux questions tranchent le reste

Lecture seule, ou écriture ?

Si c'est l'écriture, le sujet cesse d'être un sujet d'outil pour devenir un sujet de gouvernance.

Qui autorise la connexion ?

Sur les méthodes 1 et 2, une connexion établie par un super admin donne à l'assistant le périmètre d'un super admin, en pratique le portail entier. Si cette phrase fait hésiter, la réponse est la méthode 3.

HubSpot recommande de tester tout usage en écriture ou en suppression sur un compte hors production, avec un avertissement rarement cité en entier : les modèles de langage sont sujets aux hallucinations, et toute demande d'autorisation d'un outil qui modifie le compte doit être relue avant d'être accordée. Un branchement en écriture directement sur un portail de production n'est pas un choix d'outillage discutable. C'est une faute d'exploitation.

Top 5 des usages à ouvrir en premier

Nous priorisons par réversibilité de l'erreur plutôt que par valeur perçue de l'usage.

Une erreur de lecture coûte une relecture. La même erreur sur une étape de transaction pollue le reporting, les prévisions, et parfois une séquence d'emails partie sans que personne l'ait demandé. Le bon premier usage est celui dont l'erreur est visible et annulable en une minute, pas celui qui impressionne en démonstration interne.

1. La revue de pipeline sur incohérences. Dates de clôture dépassées, transactions sans activité depuis trois semaines, montants hors distribution habituelle, enregistrements rattachés à un propriétaire inactif. Aucune écriture, donc aucun enregistrement abîmé en cas d'erreur, et une question que les directions commerciales se posent déjà chaque semaine. C'est le premier usage à ouvrir, quelle que soit la méthode retenue.

2. Le diagnostic de structuration du portail. Faire décrire l'usage réel des propriétés, des étapes et des pipelines, puis comparer au paramétrage supposé. L'écart est le vrai livrable, et il est systématiquement plus large que ce que l'équipe anticipe. Cet usage a une seconde fonction : la nature des réponses fausses indique où le portail est mal structuré, la cause se trouvant presque toujours dans la donnée plutôt que dans le modèle.

3. La préparation de rendez-vous et de revue de comptes. Synthèse avant un appel : contacts et rôles, historique d'activités, tickets ouverts, transactions passées et perdues. Gain de temps immédiat, aucune écriture, adoption spontanée par les commerciaux.

4. La journalisation d'activités et des relances. Notes, comptes rendus d'appel, tâches assignées à l'issue d'une revue de pipeline. Première entrée en écriture recommandée : une note erronée se supprime, rien ne se propage.

5. La normalisation de champs sur lot restreint. Un lot identifié, relu à la main, exécuté ensuite. La relecture est la seule protection réelle, pour une raison développée plus bas : les garde-fous natifs de HubSpot sur les mises à jour groupées se contournent.

Les usages 4 et 5 gagnent à passer par un jeton restreint plutôt que par les droits d'un utilisateur. Un jeton limité à l'écriture d'activités ne peut pas déplacer une transaction, quelle que soit la formulation de la demande.

À laisser fermé au départ : étapes et montants de transaction, avec leur effet direct sur les prévisions ; fusion et suppression d'enregistrements ; actions de masse sur les contacts, avec le volet consentement que cela emporte. Ces usages s'ouvrent un jour, sous deux conditions non négociables : journalisation en place, et un propriétaire identifié de la relecture.

Cette liste est volontairement resserrée aux cinq usages que nous recommandons d'ouvrir en premier. Le catalogue complet, avec les prompts, les prérequis de structuration et les garde-fous à poser usage par usage, fera l'objet d'un article dédié.

La gouvernance des permissions, le point aveugle

Le sujet a été posé publiquement dans les discussions RevOps de la communauté HubSpot entre mai et juillet 2026, sans réponse officielle à ce jour. Trois constats en ressortent.

Il n'existe pas de couche d'administration propre au connecteur : les permissions sont celles de l'utilisateur, sans réglage intermédiaire pour un administrateur. Le garde-fou des 10 enregistrements en mise à jour groupée se contourne en demandant à l'assistant de boucler par petits lots. Et des restrictions au niveau objet ont été franchies, dont un cas de transaction verrouillée dans l'interface et pourtant conclue via le connecteur.

Aucun de ces points n'est un défaut de Claude. Ce sont des défauts de modèle de permissions, révélés par un canal qui exécute des instructions en langage naturel à la vitesse d'une API. Un portail dont les rôles sont mal découpés ne devient pas dangereux parce qu'on y branche un assistant : il l'était déjà, et le branchement rend l'exposition visible. Pour une organisation encore en amont du choix d'outil, la finesse du modèle de permissions mérite d'ailleurs d'entrer dans la grille de décision CRM, au même titre que les fonctionnalités.

Le corollaire vaut pour la donnée. Un portail dont la base est sale ne devient pas interrogeable. Il devient interrogeable de façon confiante et fausse, nettement moins confortable qu'une absence de réponse. Le sujet de fond reste la structuration, traité dans notre article sur l'enrichissement de données CRM sans polluer sa base.

Notre cadrage en cinq étapes

Cette séquence s'applique en général à la suite d'un audit de votre donnée et de vos cas d'usage.

1. Lecture seule pendant deux à quatre semaines. Identifier les questions réellement posées, et repérer où les réponses sont fausses. Elles le sont toujours quelque part.
2. Cartographier les réponses fausses. Chaque erreur remonte à une cause de structuration : propriété ambiguë, historique non nettoyé, association manquante. La liste devient un backlog de remise en état.
3. Restreindre le périmètre. Un utilisateur technique dédié sur le serveur officiel, un jeton de service aux portées minimales en auto-hébergé. La seconde option est plus propre. Elle coûte une demi-journée d'ingénierie, ce qui explique qu'elle soit si peu retenue, rarement pour de bonnes raisons.
4. Ouvrir l'écriture sur sandbox, puis sur un périmètre d'objets restreint en production. Les activités avant les transactions, les notes avant les étapes de pipeline.
5. Journaliser et relire. Sinon personne ne saura dire, dans six mois, pourquoi 400 transactions ont changé d'étape un mardi soir.

Avant d'ouvrir l'écriture, la ligne à remplir est celle du propriétaire de la relecture. Sans nom dessus, les cinq étapes ne tiennent pas.