Configurer le MCP Snowflake pour Notion

Vos custom agents et votre agent Notion peuvent se connecter à Snowflake via un serveur MCP (Model Context Protocol) exécuté par Snowflake. Une fois configuré, vous pouvez interroger votre agent sur les données de votre entrepôt Snowflake et obtenir des réponses directement dans Notion.

La configuration se déroule en plusieurs étapes, et différentes personnes sont responsables de chacune d’elles :

• Un·e admin Snowflake configure le rôle, l’entrepôt et le serveur MCP géré par Snowflake.

• Un·e propriétaire de l’espace de travail Notion ou un·e admin configure la connexion MCP Snowflake pour l’espace de travail.

• Les membres de l’espace de travail peuvent ensuite se connecter au MCP Snowflake à partir de custom agents en utilisant leurs propres identifiants Snowflake, ou connecter Snowflake directement à leur agent Notion. Les étapes 1 à 10 de cet article sont identiques pour les deux parcours. Les parcours divergent à l’étape 11, selon l’agent que vous souhaitez connecter.

• Les outils disponibles peuvent varier en fonction de votre région cloud Snowflake.

• Le serveur MCP géré par Snowflake n’est pas disponible en Chine continentale ni dans les régions sous contrôle du gouvernement.

• Votre espace de travail Notion doit bénéficier d’un forfait Business ou Enterprise.

• Utilisez Notion sur le Web ou depuis un ordinateur. Cette fonctionnalité n’est pas disponible sur mobile.

• Votre entreprise doit disposer d’un compte Snowflake.

• Pour créer un custom agent, vous devez avoir l’autorisation de créer des agents dans votre espace de travail.

Avant que votre équipe puisse connecter Snowflake à Notion, un·e admin Snowflake doit configurer l’accès. C’est l’étape la plus complexe, à effectuer une seule fois. Travaillez avec l’admin de votre espace de travail Notion : Notion fournit une URI de redirection, et Snowflake fournit un ID client OAuth et une clé secrète.

Vous configurerez un rôle et un entrepôt, créerez le serveur MCP géré par Snowflake, lui accorderez l’accès aux ressources dont il a besoin, configurerez la portée OAuth et l’intégration de sécurité, et ajouterez une politique réseau si votre organisation en exige une.

Remplissez cette fiche avec l’admin de votre espace de travail Notion avant de commencer. Les membres peuvent ignorer cette étape et se connecter avec leurs propres comptes Snowflake une fois la configuration terminée.

Le nom d’hôte du compte utilise des traits d’union, pas des traits de soulignement. Vérifiez que chaque nom d’objet dans l’URL du serveur correspond à celui utilisé dans Snowflake.

Utilisez un rôle dédié avec les moindres privilèges et un entrepôt approuvé dans la mesure du possible.

Rôle restreint sans rôles secondaires (recommandé). Ce modèle est plus facile à comprendre et à auditer. Définissez OAUTH_USE_SECONDARY_ROLES = NONE, spécifiez ALLOWED_ROLES_LIST et utilisez la portée Notion session:role:<role_acces_mcp>.

Rôles secondaires par défaut d’un utilisateur ou d’une utilisatrice (facultatif). Utilisez ce modèle uniquement lorsque le serveur a besoin de privilèges hérités des DEFAULT_SECONDARY_ROLES Snowflake de chaque utilisateur ou utilisatrice. Définissez OAUTH_USE_SECONDARY_ROLES = IMPLICIT, omettez ALLOWED_ROLES_LIST et utilisez une portée de rôle principal explicite. Snowflake n’autorise pas les rôles secondaires IMPLICIT avec ALLOWED_ROLES_LIST ; par conséquent, omettez la liste d’autorisations lorsque vous utilisez ce modèle.

Dans la mesure du possible, utilisez un rôle dédié doté des moindres privilèges pour le serveur MCP.

Accordez ce rôle via votre processus habituel de gestion des identités. Si Okta ou SCIM gère l’appartenance aux rôles Snowflake, n’ajoutez pas d’utilisateurs ou utilisatrices manuellement en dehors de ce processus.

Créez ou choisissez une base de données et un schéma appartenant à l’équipe qui exécutera le serveur.

Pour les questions métier encadrées, vous pouvez proposer un Agent Cortex comme outil aux membres. Il regroupe les vues sémantiques, les requêtes vérifiées, la fonction Chercher et l’orchestration. Un Agent Cortex est facultatif. Si vous en créez un, utilisez la spécification ci-dessous. Si vous remplacez un agent existant, assurez-vous que le nouveau respecte votre spécification approuvée.

Les autres types d’outils MCP Snowflake pris en charge incluent CORTEX_ANALYST_MESSAGE, CORTEX_SEARCH_SERVICE_QUERY, GENERIC et SYSTEM_EXECUTE_SQL.

Donnez à chaque outil un nom et une description clairs. Expliquez quelles données il couvre, quel est le niveau de détail de ses résultats et quand l’utiliser. Cela aide l’agent à choisir le bon outil.

Le privilège USAGE sur un serveur MCP permet à un rôle de se connecter au serveur et de découvrir ses outils. Il ne donne pas au rôle l’accès à l’entrepôt, à l’agent, à la vue sémantique, au service Chercher, à la procédure stockée ou aux données sous-jacentes. Accordez au rôle l’accès à chaque ressource dont les outils du serveur ont besoin.

Accordez l’accès uniquement aux ressources supplémentaires dont chaque outil a besoin. Par exemple, accordez SELECT sur une vue sémantique approuvée, USAGE sur un service Cortex Search, ou USAGE sur une fonction ou une procédure spécifique. N’accordez pas le rôle à PUBLIC et n’ajoutez pas de privilèges étendus pour les objets actuels ou futurs.

Avant de configurer OAuth, vérifiez le serveur MCP et ses attributions :

Configurez le schéma MCP pour annoncer le rôle exact que les membres doivent demander :

Utilisez une portée de rôle explicite. N’utilisez pas session:role:all. Snowflake traite cette valeur comme le rôle principal par défaut de l’utilisateur ou l’utilisatrice, et non comme un accès à tous les rôles, et les politiques pour les rôles privilégiés peuvent la bloquer. Un rôle explicite rend l’accès demandé clair et plus facile à vérifier.

Avant d’exécuter ce SQL, coordonnez-vous avec l’admin de votre espace de travail Notion. Demandez-lui de saisir l’URL du serveur Snowflake dans le formulaire de configuration MCP de l’espace de travail et d’activer Configurer manuellement l’authentification et Utiliser un client OAuth partagé par l’espace de travail. Notion génère une URI de redirection. Copiez-la et envoyez-la à l’admin Snowflake. Une fois que Snowflake a créé l’ID client et la clé secrète, l’admin de l’espace de travail peut terminer la configuration de la connexion.

Utilisez l’URI de redirection exactement telle que Notion vous la fournit. N’ajoutez ni barre oblique finale ni paramètres de requête, et ne modifiez pas l’hôte.

Le paramètre IS_AGENTIC = TRUE marque les sessions créées via cette intégration comme des sessions d’agent. La fonction IS_AGENT_ACTIVATED() de Snowflake renvoie alors TRUE, ce qui permet à Snowflake d’appliquer l’audit et la gouvernance spécifiques aux agents. Si vous utilisez le modèle de rôle secondaire facultatif, définissez OAUTH_USE_SECONDARY_ROLES = IMPLICIT et omettez ALLOWED_ROLES_LIST.

La valeur de validité du jeton d’actualisation de 7776000 secondes équivaut à 90 jours. Avant de l’utiliser, confirmez qu’elle est conforme aux politiques de réautorisation et de rotation des jetons de votre organisation. Pour les modifications courantes, évitez CREATE OR REPLACE SECURITY INTEGRATION. Le remplacement de l’intégration peut interrompre les connexions existantes.

Pour vérifier l’intégration sans afficher sa clé secrète, exécutez :

Assurez-vous que l’intégration est activée, que l’URI de redirection correspond exactement, que le rôle est autorisé et non bloqué, que les jetons d’actualisation et PKCE sont activés, et que les points d’accès d’autorisation et de jeton utilisent l’hôte de compte public de Snowflake.

Cette étape est nécessaire uniquement si votre organisation exige une politique réseau. Demandez à votre responsable de la sécurité ou réseau d’approuver les plages de sortie actuelles de Notion.

L’intégration OAuth doit autoriser les deux flux Notion :

1. le flux de l’API qui gère les rappels OAuth et les échanges de codes d’autorisation

2. le flux d’exécution de l’espace de travail qui valide la connexion, exécute les outils et actualise les jetons

Ces flux peuvent utiliser différentes adresses de sortie Notion. Si vous n’autorisez que l’adresse utilisée lors de l’échange initial de jetons, la connexion peut réussir, mais la validation ou l’actualisation du jeton peut échouer. Utilisez les plages de sortie actuelles et approuvées de Notion. N’ajoutez pas d’adresse IP ponctuelle provenant d’un navigateur ou d’un journal à une liste d’autorisations de production.

Appliquez cette politique réseau à l’intégration OAuth, et non aux utilisateurs et utilisatrices individuel·les. Ne modifiez pas vos politiques à l’échelle du compte pour la connexion par navigateur, l’accès VPN ou l’accès réseau des utilisateurs et utilisatrices. Si une politique réseau bloque une demande de jeton, Snowflake peut renvoyer invalid_client. Cette erreur ne signifie pas nécessairement que l’ID client ou la clé secrète est incorrecte.

Exécutez cette commande dans une feuille de calcul Snowflake sécurisée. Le nom de l’intégration est sensible à la casse et s’écrit généralement en majuscules :

Partagez l’ID client et la clé secrète correspondante avec votre admin de l’espace de travail Notion en utilisant un canal sécurisé approuvé. Snowflake fournit deux clés secrètes valides, vous pouvez donc les renouveler sans interruption de service. Ne collez jamais ces clés secrètes dans la documentation, les discussions, les tickets ou le contrôle à la source.

Une fois Snowflake prêt, un·e propriétaire de l’espace de travail ou un·e admin ajoute le serveur une fois pour l’espace de travail. Les membres peuvent ensuite le trouver sans voir la clé secrète du client OAuth, qu’ils connectent le MCP Snowflake à un custom agent ou à leur propre agent Notion.

1. Accédez à Paramètres pour l’espace de travail.

2. Sélectionnez Connexions → MCP partagés de l’espace de travail.

3. Sélectionnez Nouveau MCP d’espace de travail.

Remplissez ces champs, puis sélectionnez Ajouter un serveur MCP :

Après avoir enregistré, vérifiez que la nouvelle ligne apparaît sous Partagé avec cet espace de travail et que Client OAuth de l’espace de travail indique Configuré.

Objectifs cette configuration :

• Aider les membres à trouver le serveur approuvé.

• Stocker une seule fois la clé secrète du client OAuth dans le stockage chiffré des connexions de Notion.

• S’assurer que les membres se connectent avec l’URL du serveur, le client et les portées que vous avez approuvés.

• Cette configuration ne crée pas de session Snowflake partagée et ne contourne pas les contrôles d’accès de Snowflake.

• Elle ne connecte pas automatiquement chaque membre. Chaque personne doit se connecter séparément.

Si vous supprimez cette configuration, les nouveaux membres ne pourront plus trouver le serveur. Les connexions existantes peuvent toutefois rester visibles. Par conséquent, coordonnez ce changement avec la révocation des autorisations Snowflake et la suppression des connexions existantes.

Une fois que vos admins ont préparé la connexion MCP Snowflake, il existe deux façons de l’utiliser. Si vous la configurez pour une équipe, commencez par l’étape 11A. Si vous souhaitez simplement poser vos propres questions, passez à l’étape 11B. Vous pouvez faire les deux ; ce sont des connexions distinctes.

Un custom agent offre à votre équipe un espace commun pour poser des questions sur les données Snowflake. Connectez Snowflake une seule fois, ajoutez des instructions sur vos indicateurs et vos tables, puis partagez l’agent avec votre équipe. Chaque personne qui l’utilise doit se connecter à Snowflake avec ses propres identifiants : elle reçoit ainsi des réponses fondées uniquement sur les données auxquelles elle a accès.

Connecter Snowflake à un custom agent

1. Ouvrez votre custom agent, ou créez-en un.

2. Accédez à Paramètres → Outils et accès.

3. Sélectionnez Ajouter une connexion, puis choisissez le serveur Snowflake intitulé Géré par l’espace de travail. Ne sélectionnez pas Serveur MCP personnalisé et ne saisissez pas l’URL du serveur manuellement.

4. Connectez-vous à Snowflake dans votre navigateur. La page de connexion habituelle via Okta ou l’authentification unique (SSO) de votre organisation peut apparaître.

5. Examinez et approuvez le rôle Snowflake demandé.

6. Choisissez les outils que l’agent peut utiliser. Laissez les outils d’écriture et CORTEX_AGENT_RUN configurés pour demander une approbation jusqu’à ce que vous les ayez testés.

7. Sélectionnez Connecter, puis vérifiez que la connexion affiche l’état Connecté.

Donner du contexte à l’agent

La connexion permet à l’agent d’accéder à Snowflake. Vos instructions lui indiquent comment votre entreprise utilise ces données. Dans les instructions de l’agent, décrivez quels outils utiliser selon le type de question, comment votre équipe définit les indicateurs clés et par quelles tables ou vues sémantiques commencer. Quelques exemples de questions vérifiées sont très utiles. Pour un point de départ prêt à l’emploi, consultez le guide de la boîte à outils Data Scout.

Partager l’agent

Partagez l’agent avec votre équipe comme n’importe quel autre custom agent. La première fois qu’une personne lui pose une question nécessitant Snowflake, elle est invitée à se connecter avec son propre compte Snowflake. Aucun identifiant client ni aucune clé secrète ne lui sont demandés.

Si vous souhaitez poser vos propres questions dans votre propre discussion, connectez Snowflake à votre agent Notion. Vous vous connectez avec votre compte Snowflake personnel : votre agent accède uniquement aux données que vous êtes autorisé·e à consulter.

1. Accédez à Paramètres → IA de Notion.

2. Sous Serveurs MCP, sélectionnez Ajouter un serveur MCP.

3. Sélectionnez le serveur Snowflake intitulé Géré par l’espace de travail. Ne sélectionnez pas Serveur MCP personnalisé et ne saisissez pas l’URL du serveur manuellement.

4. Sélectionnez Connecter.

5. Connectez-vous à Snowflake dans votre navigateur. La page de connexion habituelle via Okta ou l’authentification unique (SSO) de votre organisation peut apparaître.

6. Examinez et approuvez le rôle Snowflake demandé.

7. Lorsque votre navigateur vous demande si vous souhaitez ouvrir Notion, sélectionnez Ouvrir Notion.

8. Vérifiez que l’état du serveur est Connecté et non Nécessite une authentification.

Une fois la connexion établie, Snowflake apparaît dans Toutes les sources → Serveurs MCP dans la discussion.

1. Posez une question anodine dont la réponse est connue et devrait provenir de Snowflake.

2. Vérifiez que l’agent utilise Snowflake et renvoie un résultat.

3. Vérifiez que vous ne pouvez pas accéder aux données en dehors du rôle qui vous a été attribué.

Si vous avez configuré un custom agent, demandez aussi à un membre de votre équipe ayant un rôle Snowflake plus restreint de l’essayer. Cette personne doit voir uniquement ses propres données, pas les vôtres. C’est le moyen le plus rapide de vérifier que l’agent utilise l’accès de chaque personne, et non celui de la personne qui l’a créé.

Pour une vérification plus approfondie, demandez à votre admin Snowflake de confirmer votre identité d’utilisateur, votre rôle, votre entrepôt et l’historique de vos requêtes. Une connexion réussie confirme votre identité, mais pas que toutes les autorisations sont correctes.

Posez à l’agent une question précise sur vos données Snowflake. Par exemple :

• « Dans Snowflake, quel a été le nombre total d’inscriptions le mois dernier ? »

• « Dans Snowflake, quels ont été nos 10 comptes générant le plus de revenus ce trimestre ? »

Avec un custom agent, vous pouvez généralement omettre « dans Snowflake » dès que ses instructions précisent quand l’utiliser. Avec votre agent Notion, mentionner Snowflake l’aide à choisir la bonne source.

Les requêtes volumineuses peuvent prendre plus de temps ou expirer. Si cela se produit, posez une question plus précise ou divisez la requête en questions plus courtes.

La plupart du temps, vous restez connecté·e sans rien faire. Snowflake utilise des jetons d’accès à courte durée de vie, et Notion les actualise en arrière-plan. L’expiration d’un jeton d’accès à elle seule ne vous déconnectera pas.

Vous devrez vous reconnecter dans les cas suivants :

• Votre jeton d’actualisation expire ou un·e admin le révoque

• Un·e admin remplace l’intégration OAuth ou la clé secrète du client

• Votre rôle Snowflake est supprimé

• Un·e admin supprime la configuration de l’espace de travail ou votre connexion

• Une politique réseau bloque l’actualisation du jeton

Avec un custom agent, chaque personne se connecte séparément. Si quelqu’un doit se reconnecter, cela n’affecte personne d’autre. La personne qui a créé l’agent n’a rien à faire.

Si vous effectuez une rotation de la clé secrète du client : utilisez la rotation à deux clés secrètes de Snowflake au lieu de remplacer l’intégration. Gardez les deux clés secrètes valides le temps de mettre à jour et de tester la configuration de l’espace de travail avant de retirer l’ancienne.

ALTER SECURITY INTEGRATION <nom_integration_oauth>
REFRESH OAUTH_CLIENT_SECRET_2;

• La connexion MCP à Snowflake n’apparaît pas dans la liste. L’admin de votre espace de travail ne l’a peut-être pas encore ajoutée, ou votre espace de travail limite peut-être les serveurs personnalisés. Demandez de l’aide à votre admin.

• On vous demande un identifiant client ou une clé secrète. Vous avez probablement choisi l’option MCP personnalisée. Revenez en arrière et choisissez plutôt le serveur Snowflake intitulé Géré par l’espace de travail.

• On vous demande de vous reconnecter. Votre session Snowflake a peut-être expiré, ou un·e admin a peut-être mis à jour la connexion. Reconnectez-vous à Snowflake.

• Vous avez ouvert un custom agent et il vous a demandé de vous connecter à Snowflake. C’est normal la première fois. Chaque personne utilisant un custom agent géré doit se connecter avec ses propres identifiants Snowflake.

• Un membre de votre équipe obtient des résultats différents avec le même custom agent. C’est normal. L’agent utilise l’accès Snowflake de chaque personne : des rôles différents donnent accès à des données différentes.

• Le custom agent fonctionne dans une discussion, mais pas selon une fréquence définie. Les exécutions planifiées ou déclenchées ne sont associées à aucune personne connectée. Elles ne peuvent donc pas encore utiliser Snowflake avec une connexion individuelle.

• Vous vous êtes connecté·e, mais la connexion ne s’établit pas ou les outils échouent. La connexion prouve votre identité, mais votre accès dépend toujours de vos autorisations Snowflake. Demandez à votre admin Snowflake de vérifier que votre rôle donne accès au serveur, à l’entrepôt, à l’agent et aux données.

• L’agent ne trouve pas de table. L’agent accède uniquement aux données accessibles depuis votre compte Snowflake. Vérifiez vos autorisations Snowflake et indiquez le nom de la table dans votre question.

• Une requête expire. Posez une question plus précise ou divisez votre requête en questions plus courtes.

Ces erreurs proviennent généralement des paramètres Snowflake, et non de Notion. Partagez-les avec votre admin Snowflake.

• L’URL du serveur semble en double, comme https://https%3A... L’adresse a été collée avec un https:// supplémentaire au début. Corrigez-la pour que l’URL commence par un seul https://.

• Vous voyez le message « This server does not support OAuth authentication. » L’intégration de sécurité n’est pas configurée pour OAuth, ou l’URL du serveur est incorrecte. Demandez à votre admin Snowflake de vérifier l’intégration de sécurité OAuth et l’URL du serveur.

• Vous voyez invalid_client lors de la connexion ou de l’actualisation. L’ID client ou la clé secrète est incorrecte, ou la clé secrète a été modifiée. Demandez à votre admin l’ID client et la clé secrète actuels.

• La connexion fonctionne, puis échoue immédiatement. Votre rôle ne donne peut-être pas accès au serveur, ou un rôle ou une règle réseau bloque la session. Demandez à votre admin de vérifier vos autorisations et vos politiques.

• Vous voyez le message « The role ALL requested has been explicitly blocked. » La connexion a demandé tous les rôles à la fois (session:role:all), ce qui donne lieu à un blocage. Utilisez plutôt un rôle précis, comme session:role:analyst, avec le nom réel de votre rôle.

• Vous voyez une erreur de redirection (erreur 390307). L’URL de redirection enregistrée dans Snowflake ne correspond pas à celle utilisée par Notion. Demandez à votre admin de définir l’URL de redirection dans l’intégration de sécurité sur la valeur exacte utilisée par Notion.

• Vous voyez l’erreur 390311 concernant un défi de code non valide. Il s’agit d’une incompatibilité PKCE. Demandez à votre admin de vérifier que OAUTH_ENFORCE_PKCE est correctement défini dans l’intégration de sécurité.

• Vous êtes connecté·e, mais aucun outil ne s’affiche. Votre rôle n’a peut-être pas le privilège USAGE sur le serveur MCP. Demandez à votre admin de vérifier que ce privilège a été accordé, puis exécutez DESCRIBE MCP SERVER pour vérifier la configuration.

• Vous pouvez accéder à plus ou moins de données que prévu. Les rôles secondaires modifient ce que votre session peut voir. Vérifiez avec votre admin quels rôles sont actifs dans votre session.

• Cela fonctionnait avant, mais depuis le changement de clé secrète, plus personne ne parvient à se connecter. La clé secrète du client a été renouvelée : la connexion enregistrée n’est donc plus à jour. Demandez la nouvelle clé secrète à votre admin, puis reconnectez-vous.

• Cela fonctionnait avant, mais maintenant, la connexion échoue uniquement pour vous. Un rôle, un privilège ou une politique a peut-être changé, ou votre session a expiré. Connectez-vous à nouveau, puis demandez à votre admin de vérifier que vos droits d’accès n’ont pas changé.

• Votre identifiant de compte est rejeté. Utilisez le format organisation-compte avec un trait d’union, comme monorg-moncompte, sans points.

• Un compte PrivateLink ne peut pas se connecter. Les comptes PrivateLink nécessitent une configuration réseau supplémentaire. Demandez à votre admin si PrivateLink autorise les connexions à Notion.

• Snowflake n’est pas disponible dans les exécutions planifiées ou déclenchées. Ces exécutions ne sont associées à aucune personne connectée et ne peuvent donc pas encore utiliser de connexion individuelle. Exécutez plutôt votre demande dans la discussion.

• Vous voyez oauth_security_error après une connexion via le navigateur. Une politique réseau au niveau du compte peut bloquer la demande. Votre admin peut le vérifier en exécutant la commande suivante :

• La connexion semble fonctionner mais vous obtenez une erreur de rôle, même avec la bonne portée. Votre rôle par défaut peut être bloqué, par exemple ACCOUNTADMIN ou un rôle dans BLOCKED_ROLES_LIST. Votre admin peut vérifier et corriger cela :

Ces commandes en lecture seule aident votre admin à vérifier la configuration sans rien modifier. Exécutez-les dans Snowflake.

Utilisez ces guides Snowflake pour terminer la configuration :

• Serveur MCP géré par Snowflake

• Créer une intégration de sécurité OAuth Snowflake

• OAuth Snowflake pour les clients personnalisés

• Présentation de l’OAuth Snowflake

• Identifiants de compte Snowflake

• Custom agents

• Connexions MCP pour les custom agents

• Connectez des serveurs MCP à votre agent Notion

• Meilleures pratiques de sécurité pour les connexions d’agent