Configurer le serveur Braze MCP

Découvrez comment vous connecter au serveur Braze MCP distant, vous authentifier avec OAuth et commencer à utiliser les outils Braze depuis votre client MCP. Pour plus d’informations, consultez Serveur Braze MCP.

Important

Le serveur MCP Braze hébergé localement (bêta) est obsolète et ne reçoit plus de mises à jour.

Conditions préalables

Avant de commencer, vérifiez que vous disposez des éléments suivants :

Remarque

Les accès de votre agent reflètent vos autorisations sur le tableau de bord. Si votre accès au tableau de bord est limité à une équipe plutôt qu’à un espace de travail complet, certains outils risquent de ne pas fonctionner.

Gérer l’accès (pour les administrateurs)

Remarque

Avant que les utilisateurs puissent se connecter, un administrateur de l’entreprise doit activer l’accès OAuth MCP dans Paramètres > Paramètres d’administration > OAuth. Pour plus d’informations, consultez Gérer les paramètres OAuth.

Accorder l’accès

Les administrateurs contrôlent l’accès au serveur MCP à l’aide de l’autorisation « Utiliser le serveur MCP ». Par défaut, les utilisateurs ne disposent pas de cette autorisation : elle doit leur être accordée explicitement.

Révoquer l’accès

Pour révoquer l’accès, retirez l’autorisation « Utiliser le serveur MCP » de l’utilisateur. Lorsque vous retirez des autorisations du tableau de bord à un utilisateur, ces fonctionnalités sont également retirées à tout agent connecté dès la requête suivante.

Si vous pensez qu’un jeton a été divulgué ou utilisé de manière abusive, un administrateur de l’entreprise peut révoquer en une seule fois tous les jetons OAuth MCP de l’entreprise dans Paramètres > Paramètres d’administration > OAuth. Tous les clients connectés perdent alors l’accès et tous les utilisateurs doivent se reconnecter. Pour plus d’informations, consultez Révoquer les jetons OAuth MCP.

Auditer l’utilisation

Lorsqu’un utilisateur se connecte avec succès via OAuth, un événement est enregistré dans le rapport d’événements de sécurité.

Connecter votre client

Étape 1 : Vérifier les autorisations et l’accès aux espaces de travail

1. Vérifiez que vous disposez de l’autorisation « Use MCP Server ». Sinon, demandez à l’administrateur de votre entreprise de la vérifier pour vous.
2. Si vous avez besoin d’accéder à plusieurs espaces de travail, vérifiez que l’autorisation est activée pour chacun d’eux.
3. Demandez à l’administrateur de votre entreprise de confirmer que l’URI de redirection de votre client est approuvée dans les paramètres OAuth. Dans le cas contraire, vous ne pourrez pas terminer la connexion à Braze à l’étape 3.

Étape 2 : Ajouter Braze comme connecteur MCP distant

Dans votre client MCP, ajoutez un nouveau serveur distant ou un connecteur personnalisé, puis saisissez l’URL MCP de Braze. Par exemple, dans Claude, accédez à Settings > Connectors > Add custom connector et collez l’URL.

Aucun ID client, secret client ni clé API n’est nécessaire. Votre client s’enregistre automatiquement auprès de Braze. Cet enregistrement n’approuve pas l’URI de redirection du client pour votre entreprise : un administrateur doit donc toujours l’approuver, comme décrit à l’étape 1.

Endpoints MCP de Braze disponibles :

• https://mcp.braze.com/mcp (États-Unis)
• https://mcp.braze.eu/mcp (UE)

Conseil

Les clients situés dans l’UE doivent utiliser l’endpoint UE. Les clients situés hors de l’UE peuvent utiliser l’un ou l’autre.

Guides de configuration des clients :

• Claude
• Claude Code
• ChatGPT
• Cursor
• OpenAI Codex
• Visual Studio Code

Étape 3 : Se connecter à Braze via OAuth

La première fois que votre agent appelle un outil Braze, votre client ouvre une fenêtre de navigateur et vous redirige vers Braze pour vous connecter.

1. Connectez-vous à Braze comme d’habitude, y compris via l’authentification unique si nécessaire.
2. Si votre identifiant donne accès à plusieurs entreprises sur le même cluster, sélectionnez l’entreprise à utiliser.
3. Sur l’écran de consentement, examinez les accès demandés par l’application.
4. Cochez la case de confirmation pour accepter la politique de confidentialité de Braze, puis sélectionnez Continuer pour revenir à votre client MCP.

Votre session utilise des jetons d’accès de courte durée qui s’actualisent automatiquement. Il peut arriver que vous deviez vous reconnecter.

Étape 4 : Indiquer à votre agent l’espace de travail à utiliser

Si votre compte donne accès à plusieurs espaces de travail, précisez l’espace de travail dans votre prompt. Par exemple :

• I'd like to look at campaign analytics for the past week in the Production workspace.
• Can you compare this week's analytics between my prod-1 workspace and my prod-2 workspace?

Si vous ne précisez pas d’espace de travail, votre agent peut vous demander de le préciser.

Étape 5 : Envoyer un prompt de test

Une fois la configuration terminée, envoyez un prompt de validation rapide, par exemple :

• List the Braze tools available in this workspace.
• Show my recent Canvases from the Production workspace.

Pour plus d’exemples, consultez Utiliser le serveur Braze MCP.

Exemple : connexion avec Claude

Connecter un client ne prend que quelques étapes. Cette procédure utilise Claude, mais le processus est similaire pour les autres clients pris en charge.

Avant de commencer, vérifiez qu’un administrateur de l’entreprise a approuvé l’URI de redirection de votre client, comme décrit à l’étape 1.

1. Dans Claude, accédez à Paramètres > Connecteurs > Ajouter un connecteur personnalisé.
2. Saisissez un nom, par exemple Braze, puis collez l’URL de votre serveur Braze MCP : https://mcp.braze.com/mcp pour les États-Unis ou https://mcp.braze.eu/mcp pour l’UE. Vous n’avez pas besoin d’ID client, de secret client ni de clé API.
3. Sélectionnez Ajouter pour enregistrer le connecteur. Claude s’enregistre automatiquement auprès de Braze, mais cela n’approuve pas son URI de redirection pour votre entreprise.
4. Sélectionnez Connecter pour lancer l’authentification. Claude ouvre une fenêtre de navigateur et vous redirige vers Braze pour vous connecter.
5. Connectez-vous à Braze avec vos identifiants habituels, y compris l’authentification unique si votre entreprise l’utilise. Si votre identifiant donne accès à plusieurs entreprises sur le même cluster, sélectionnez celle que vous souhaitez utiliser.
6. Sur l’écran de consentement, vérifiez les accès demandés, cochez la case de confirmation, puis sélectionnez Continuer. Claude vous ramène à votre conversation, et votre agent peut désormais utiliser les outils Braze.

Pour vérifier la connexion, envoyez une invite de test, par exemple Show my recent Canvases from the Production workspace.

Migration depuis le serveur bêta local

Pendant la migration, vous pouvez faire fonctionner le serveur bêta local et le serveur hébergé à distance en parallèle. Vous devrez peut-être indiquer explicitement à votre agent lequel utiliser.

Le serveur hébergé à distance propose de nouveaux outils qui n’existent pas dans le serveur bêta local. Si vous avez créé des compétences pour le serveur local, vous devrez peut-être les mettre à jour pour qu’elles fassent référence aux nouveaux noms d’outils et à leur nouveau comportement.

Une fois que vous avez vérifié que vos flux de travail et vos compétences fonctionnent sur le serveur distant, désactivez le serveur hébergé localement.

Résolution des problèmes

L’authentification échoue dans un client pris en charge

1. Vérifiez que l’administrateur de votre entreprise a activé l’accès OAuth MCP dans les paramètres OAuth.
2. Vérifiez que votre utilisateur dispose de l’autorisation « Utiliser le serveur MCP ».
3. Vérifiez que l’URI de redirection de votre client est approuvée. Si le message « Cette application nécessite une approbation » ou une erreur générique telle que « Une erreur inattendue s’est produite » s’affiche à l’étape de consentement, demandez à l’administrateur de votre entreprise de vérifier que le statut de l’URI de redirection est Approuvé dans les paramètres OAuth.
4. Réessayez de vous connecter et d’autoriser l’accès.

L’authentification est bloquée dans un client non vérifié

Pour des raisons de sécurité, Braze tient à jour une liste d’autorisation des domaines clients pris en charge. Si vous vous connectez depuis un client qui ne figure pas sur cette liste, l’authentification peut être bloquée. Vous souhaitez support for your MCP client ? N’hésitez pas à laisser un retour produit.

Les clients qui s’exécutent localement sur votre machine sans schéma personnalisé, comme Claude Code et OpenAI Codex, devraient également fonctionner.

Une connexion qui fonctionnait ne s’authentifie plus

Si votre client était connecté et que l’authentification échoue désormais, l’administrateur de votre entreprise a peut-être révoqué les jetons OAuth MCP de votre entreprise. Reconnectez-vous à Braze depuis votre client pour créer une nouvelle connexion. Si la connexion échoue toujours, vérifiez que l’accès OAuth MCP est activé et que vous disposez toujours de l’autorisation « Utiliser le serveur MCP ».

Les outils n’apparaissent pas dans votre client

Si votre agent ne parvient pas à lister les outils Braze, patientez quelques minutes, puis réessayez. Ces problèmes sont souvent temporaires et se résolvent d’eux-mêmes.

L’agent ne peut pas accéder aux outils attendus

1. Vérifiez que votre utilisateur du tableau de bord dispose des autorisations requises. Votre agent ne peut utiliser que les outils correspondant à vos propres accès au tableau de bord.
2. Vérifiez que vous avez sélectionné l’espace de travail attendu dans votre requête.
3. Demandez à votre agent d’appeler get_workspaces et vérifiez les ID d’espaces de travail disponibles.

L’agent utilise le mauvais espace de travail

Si votre compte a accès à plusieurs espaces de travail, indiquez l’espace de travail dans votre requête en utilisant le nom exact affiché dans le tableau de bord de Braze. Si vous ne précisez pas d’espace de travail, votre agent peut vous demander de le préciser ou en utiliser un inattendu.

Important

Avant que votre agent ne commence à travailler, vérifiez toujours quel espace de travail il utilise. Dans certains cas, un agent peut sélectionner un espace de travail différent de celui que vous aviez prévu.

Passer à une autre entreprise

Votre entreprise est définie lors de votre première autorisation. Pour travailler dans une autre entreprise sur le même cluster, déconnectez le connecteur Braze dans votre client, autorisez à nouveau l’accès et sélectionnez l’autre entreprise lors de la connexion.

Clause de non-responsabilité

Comment les instructions et les réponses sont traitées

Le serveur MCP de Braze reçoit les instructions de votre client MCP tiers, tel que Claude, ChatGPT, Copilot, Gemini CLI, Codex ou Cursor, exactement telles que le modèle d’IA sous-jacent de ce fournisseur les formule. Lorsque vous saisissez une requête en langage naturel, le modèle d’IA interprète votre requête et la traduit en un ou plusieurs appels d’outils spécifiques vers Braze. Braze reçoit et exécute l’appel d’outil tel qu’il est envoyé. Braze ne voit pas votre prompt original en langage naturel et ne peut pas vérifier que l’appel d’outil généré reflète fidèlement ou intégralement votre requête initiale.

Lorsque Braze renvoie des données ou un résultat, cette réponse est transmise à votre client MCP tiers, qui l’interprète, la met en forme et vous la présente. Braze ne contrôle pas la manière dont le modèle d’IA présente, résume ou décrit les informations renvoyées.

Braze décline toute responsabilité quant aux instructions générées par, ou aux réponses transmises via, tout client MCP tiers. Braze recommande de ne pas utiliser le « mode automatique » si votre client MCP tiers le propose pour la mise en œuvre automatique d’actions. Vérifiez les résumés générés par l’IA en les comparant aux données sources dans votre tableau de bord de Braze et examinez toute action proposée par l’IA avant de la mettre en œuvre via votre client MCP tiers.