Configurer le MCP Snowflake pour Notion

Vos Custom Agents et votre Notion Agent 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 administrateur Snowflake configure le rôle, l'entrepôt et le serveur MCP géré par Snowflake.

• Un propriétaire ou un administrateur d'espace de travail Notion 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 d'agents personnalisés 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 chemins. Les chemins se séparent à 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 ou dans les régions gouvernementales.

• Votre espace de travail Notion doit être sur un plan Business ou Enterprise.

• Utilisez Notion sur le Web ou sur 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 administrateur Snowflake doit configurer l'accès. Il s'agit de l'étape la plus complexe, et vous n'avez besoin de l'effectuer qu'une seule fois. Travaillez avec l'administrateur de votre espace de travail Notion : Notion fournit un URI de redirection, et Snowflake fournit un ID client OAuth et un secret.

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'administrateur 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. Assurez-vous que chaque nom d'objet dans l'URL du serveur correspond au nom d'objet correspondant dans Snowflake.

Utilisez un rôle dédié avec le moins de privilèges possible 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:<mcp_access_role>.

Rôles secondaires par défaut d'un utilisateur (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. 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, omettez donc la liste d’autorisations lorsque vous utilisez ce modèle.

Utilisez un rôle dédié avec le moins de privilèges possible pour le serveur MCP dans la mesure du possible.

Accordez ce rôle via votre processus habituel de gestion des identités. Si Okta ou SCIM gère les membres du rôle Snowflake, n'ajoutez pas d'utilisateurs 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 régies, vous pouvez exposer un Cortex Agent en tant qu’outil utilisé par les membres. Il conserve les vues sémantiques, les requêtes vérifiées, Chercher et l'orchestration au même endroit. Un Cortex Agent est facultatif. Si vous en créez un, utilisez la spécification ci-dessous. Si vous remplacez un agent existant, assurez-vous que le remplacement correspond à 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 Chercher, 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 privilèges accordés :

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, et non comme un accès à chaque rôle, et les politiques pour les rôles privilégiés peuvent le 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 Manually configure authentication et Use a workspace-shared OAuth client. Notion génère un URI de redirection. Copiez-le et envoyez-le à l'admin Snowflake. Une fois que Snowflake a créé l'ID client et le secret, l'admin peut terminer la configuration des connexions.

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

Définir 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 un audit et une 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 correspond 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 :

Confirmez 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 n'est nécessaire que si votre organisation exige une politique réseau. Demandez à votre responsable de la sécurité ou du réseau d'approuver les plages de sortie actuelles de Notion.

L'intégration OAuth doit autoriser les deux parcours Notion :

1. Le parcours de l'API qui gère les rappels OAuth et les échanges de codes d'autorisation

2. Le parcours d'exécution de l'espace de travail qui valide les connexions, exécute les outils et actualise les jetons

Ces chemins 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 une adresse IP ponctuelle provenant d'un navigateur ou d'un journal à une liste d'autorisation de production.

Attachez cette politique réseau à l'intégration OAuth, et non aux utilisateurs individuels. Ne modifiez pas vos politiques à l'échelle du compte pour la connexion au navigateur, l'accès VPN ou l'accès réseau des utilisateurs. 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 le secret est incorrect.

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

Partagez l'ID client et son secret correspondant avec l'administrateur de votre espace de travail Notion en utilisant un canal sécurisé approuvé. Snowflake fournit deux secrets valides, vous pouvez donc les faire pivoter sans interruption de service. Ne collez jamais l'un ou l'autre des secrets dans la documentation, les discussions, les tickets ou le contrôle de source.

Une fois que Snowflake est prêt, un propriétaire ou un admin d'espace de travail ajoute le serveur une fois pour l'espace de travail. Les membres peuvent ensuite le trouver sans voir le secret client OAuth, qu'ils connectent le MCP Snowflake à un custom agent ou à leur propre agent Notion.

1. Allez dans Paramètres pour l'espace de travail.

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

3. Sélectionnez Nouvel espace de travail MCP.

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

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

Ce que fait cette configuration :

• Aide les membres à trouver le serveur approuvé.

• Stocke la clé secrète client OAuth une fois dans le stockage de connexions chiffré de Notion.

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

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

• Ne connecte pas chaque membre automatiquement. 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 toujours apparaître, coordonnez donc ce changement avec la révocation des accès Snowflake et la suppression des connexions existantes.

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

Un custom agent offre à votre équipe un espace unique pour poser des questions sur les données Snowflake. Vous connectez Snowflake une fois, ajoutez des instructions sur vos métriques et vos tables, puis partagez l'agent avec votre équipe. Chaque personne qui l'utilise devra se connecter à Snowflake avec ses propres identifiants, afin que chacun obtienne des réponses basées uniquement sur les données qu'il est autorisé à voir.

Connecter Snowflake à un custom agent

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

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

3. Sélectionnez Ajouter des connexions, 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 connexion Okta ou SSO habituelle 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 capables d'écriture et CORTEX_AGENT_RUN configurés pour demander une approbation jusqu'à ce que vous les ayez testés.

7. Sélectionnez Connecter, et confirmez que les connexions s'affichent comme Connecté.

Donner du contexte à l'agent

Les connexions donnent à l'agent accès à Snowflake. Vos instructions lui indiquent comment votre entreprise utilise ces données. Dans les instructions de l'agent, décrivez quels outils utiliser pour quels types de questions, comment votre équipe définit les métriques clés, et quelles tables ou vues sémantiques utiliser comme point de départ. 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 de la même manière que vous partagez n'importe quel custom agent. La première fois que quelqu'un lui posera une question nécessitant Snowflake, il sera invité à se connecter avec son propre compte Snowflake. Il ne lui sera pas demandé d'identifiant client ou de clé secrète.

Si vous souhaitez poser vos propres questions dans votre propre discussion, connectez Snowflake à votre agent Notion. Vous vous connectez avec votre propre compte Snowflake, de sorte que votre agent n'accède qu'à ce que vous êtes autorisé à voir.

1. Allez dans 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 connexion Okta ou SSO habituelle 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. Confirmez que l'État du serveur est Connecté, et non Nécessite une authentification.

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

1. Posez une question anodine avec une réponse connue qui devrait utiliser Snowflake.

2. Confirmez que l'agent utilise Snowflake et renvoie un résultat.

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

Si vous configurez un custom agent, demandez également à l'un des Membres de votre équipe ayant un rôle Snowflake plus restreint de l'essayer. Il ne devrait voir que ses propres données, pas les vôtres. C'est le moyen le plus rapide de confirmer que l'agent utilise l'accès de chaque personne plutôt que celui du créateur.

Pour une vérification plus approfondie, demandez à votre admin Snowflake de confirmer votre utilisateur, votre rôle, votre entrepôt et l'historique de vos requêtes. Une connexion réussie confirme votre identité, mais ne confirme pas que chaque autorisation est correcte.

Posez à l'agent une question spécifique sur vos données Snowflake. Par exemple :

• « Depuis Snowflake, quel a été notre nombre total d'inscriptions le mois dernier ? »

• « Depuis 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 « depuis Snowflake » une fois que ses instructions indiquent clairement quand l'utiliser. Avec votre agent Notion, mentionner Snowflake aide l'agent à 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 petites.

La plupart du temps, vous restez connecté 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 ne vous déconnectera pas automatiquement.

Vous devrez vous reconnecter si :

• Votre jeton d'actualisation expire ou un admin le révoque.

• Un admin remplace l'intégration OAuth ou la clé secrète.

• Votre rôle Snowflake est supprimé

• Un admin supprime la configuration de l'espace de travail ou vos connexions.

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

Avec un custom agent, les connexions de chaque personne sont distinctes. Si l'on demande à une personne de se reconnecter, cela n'affecte personne d'autre, et la personne qui a créé l'agent n'a rien à faire.

Si vous faites pivoter la clé secrète : 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 assez longtemps pour mettre à jour et tester la configuration de l'espace de travail avant de retirer l'ancienne.

ALTER SECURITY INTEGRATION <oauth_integration_name>
REFRESH OAUTH_CLIENT_SECRET_2;

• La connexion Snowflake MCP n'est pas répertoriée. Votre administrateur d'espace de travail ne l'a peut-être pas encore ajoutée, ou votre espace de travail peut limiter les serveurs personnalisés. Demandez de l'aide à votre administrateur.

• 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 marqué Géré par l'espace de travail.

• On vous demande de vous reconnecter. Votre session Snowflake a peut-être expiré, ou un admin a peut-être mis à jour les connexions. Connectez-vous à nouveau à 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.

• L'un des Membres 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, donc les personnes ayant des rôles différents voient des données différentes.

• Le custom agent fonctionne dans la discussion mais pas selon une fréquence. Les exécutions planifiées et déclenchées n'ont pas de personne connectée, elles ne peuvent donc pas encore utiliser Snowflake avec des connexions par personne.

• Vous vous êtes connecté, mais les connexions ne s'établissent pas ou les outils échouent. Les connexions prouvent votre identité, mais votre accès dépend toujours de vos autorisations Snowflake. Demandez à votre admin Snowflake de confirmer que votre rôle peut accéder au serveur, à l'entrepôt, à l'agent et aux données.

• L'agent ne trouve pas de table. L'agent ne peut accéder qu'aux données auxquelles votre compte Snowflake peut accéder. Vérifiez vos autorisations Snowflake et incluez 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 petites.

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 doublée, 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 « 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'identifiant client ou la clé secrète est incorrect, ou la clé secrète a été modifiée. Demandez à votre admin l'identifiant client et la clé secrète actuels.

• La connexion fonctionne, puis échoue immédiatement. Votre rôle n'atteint peut-être pas le 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 « The role ALL requested has been explicitly blocked. » La connexion a demandé tous les rôles à la fois (session:role:all), ce qui est bloqué. Utilisez plutôt un rôle exact, 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 sur l'intégration de sécurité avec la valeur Notion exacte.

• Vous voyez l'erreur 390311 concernant un défi de code invalide. Il s'agit d'une inadéquation PKCE. Demandez à votre admin de confirmer que OAUTH_ENFORCE_PKCE est correctement défini sur l'intégration de sécurité.

• Vous êtes connecté, mais aucun outil n'apparaît. Il manque peut-être à votre rôle USAGE sur le serveur MCP. Demandez à votre admin de confirmer l'autorisation, 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 quels rôles sont actifs dans votre session avec votre admin.

• Cela fonctionnait avant, et maintenant tout le monde échoue après un changement de clé secrète. La clé secrète client a été renouvelée, la connexion enregistrée est donc obsolète. Demandez à votre admin la nouvelle clé secrète, puis reconnectez-vous.

• Cela fonctionnait avant, et maintenant cela échoue uniquement pour vous. Un rôle, une autorisation ou une politique a peut-être changé, ou votre session a expiré. Connectez-vous à nouveau, puis demandez à votre admin de confirmer que votre accès n'a pas changé.

• Votre identifiant de compte est rejeté. Utilisez le format organization-account avec un trait d'union, comme myorg-myaccount, et non des 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 la connexion Notion.

• Snowflake n'est pas disponible lors des exécutions planifiées ou déclenchées. Ces exécutions ne disposent d'aucune personne connectée, elles ne peuvent donc pas encore utiliser la connexion par personne. Exécutez plutôt votre requête dans la discussion.

• Vous voyez oauth_security_error après vous être connecté via le navigateur. Une politique réseau au niveau du compte bloque peut-être la requête. Demandez à votre admin de le confirmer en exécutant :

• 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 est peut-être bloqué, par exemple ACCOUNTADMIN ou un rôle dans BLOCKED_ROLES_LIST. Demandez à votre admin de vérifier et corriger cela :

Ces commandes en lecture seule aident votre admin à confirmer 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 Snowflake OAuth

• Identifiants de compte Snowflake

• Custom agent

• Connexions MCP pour les custom agents

• Connectez des serveurs MCP à votre agent Notion

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