De Snowflake MCP voor Notion instellen

Je Aangepaste agenten en Notion-agent kunnen via een door Snowflake beheerde MCP (Model Context Protocol)-server verbinding maken met Snowflake. Zodra dit is ingesteld, kun je je agent vragen stellen over je Snowflake-warehousegegevens en direct antwoorden krijgen in Notion.

De installatie gebeurt in fasen en verschillende personen zijn verantwoordelijk voor elk onderdeel:

• Een Snowflake-beheerder stelt de rol, het warehouse en de door Snowflake beheerde MCP-server in.

• Een eigenaar of beheerder van de Notion-workspace configureert de Snowflake-MCP-verbinding voor de workspace.

• Workspaceleden kunnen vervolgens vanuit Aangepaste agenten met hun eigen Snowflake-inloggegevens verbinding maken met Snowflake-MCP, of Snowflake rechtstreeks koppelen aan hun Notion-agent. Stappen 1–10 van dit artikel zijn voor beide routes hetzelfde. De routes splitsen zich bij stap 11, afhankelijk van welke agent je wilt koppelen.

• De beschikbare tools kunnen variëren per Snowflake-cloudregio.

• De beheerde MCP-server van Snowflake is niet beschikbaar in het vasteland van China of in overheidsregio's.

• Je Notion-workspace moet een Business- of Enterprise-abonnement hebben.

• Gebruik Notion in de browser of op je computer. Deze functie is niet beschikbaar op mobiele apparaten.

• Je bedrijf heeft een Snowflake-account nodig.

• Om een Aangepaste agent te maken, heb je de machtiging nodig om agenten in je workspace aan te maken.

Voordat je team Snowflake met Notion kan verbinden, moet een Snowflake-beheerder de toegang instellen. Dit is de meest uitgebreide stap en je hoeft deze slechts één keer uit te voeren. Werk samen met je Notion-workspacebeheerder: Notion verstrekt een redirect-URI en Snowflake verstrekt een OAuth-client-ID en -secret.

Je stelt een rol en warehouse in, maakt de door Snowflake beheerde MCP-server aan, verleent deze toegang tot de benodigde resources, configureert het OAuth-bereik en de beveiligingsintegratie en voegt een netwerkbeleid toe als je organisatie dit vereist.

Vul dit werkblad in met je Notion-workspacebeheerder voordat je begint. Leden kunnen dit overslaan en inloggen met hun eigen Snowflake-accounts zodra de installatie is voltooid.

De hostnaam van het account gebruikt koppeltekens, geen underscores. Zorg ervoor dat elke objectnaam in de server-URL overeenkomt met de bijbehorende objectnaam in Snowflake.

Gebruik waar mogelijk een toegewezen rol met minimale rechten en één goedgekeurd warehouse.

Aanbevolen: een beperkte rol zonder secundaire rollen. Dit model is eenvoudiger te begrijpen en te controleren. Stel OAUTH_USE_SECONDARY_ROLES = NONE in, specificeer ALLOWED_ROLES_LIST en gebruik het Notion-bereik session:role:<mcp_access_role>.

Optioneel: de standaard secundaire rollen van een gebruiker. Gebruik dit model alleen wanneer de server rechten nodig heeft die voortkomen uit de Snowflake-instelling DEFAULT_SECONDARY_ROLES van elke gebruiker. Stel OAUTH_USE_SECONDARY_ROLES = IMPLICIT in, laat ALLOWED_ROLES_LIST weg en gebruik een expliciet bereik voor de primaire rol. Snowflake staat IMPLICIT secundaire rollen niet toe in combinatie met ALLOWED_ROLES_LIST, dus laat de lijst met toegestane rollen weg als je dit model gebruikt.

Gebruik waar mogelijk een specifieke rol met minimale rechten voor de MCP-server.

Verleen deze rol via je gebruikelijke proces voor identiteitsbeheer. Als Okta of SCIM het lidmaatschap van Snowflake-rollen beheert, voeg gebruikers dan niet handmatig buiten dat proces toe.

Maak of kies een database en schema die eigendom zijn van het team dat de server gaat draaien.

Voor zakelijke vragen met duidelijke regels kun je een Cortex Agent aanbieden als tool voor leden. Zo blijven semantische weergaven, geverifieerde query's, Search en orkestratie bij elkaar. Een Cortex Agent is optioneel. Maak je er een, gebruik dan de onderstaande specificatie. Vervang je een bestaande agent, zorg dan dat de nieuwe agent aan de goedgekeurde specificatie voldoet.

Andere ondersteunde Snowflake MCP-tooltypes zijn onder andere CORTEX_ANALYST_MESSAGE, CORTEX_SEARCH_SERVICE_QUERY, GENERIC en SYSTEM_EXECUTE_SQL.

Geef elke tool een duidelijke naam en beschrijving. Leg uit welke gegevens de tool dekt, hoe gedetailleerd de resultaten zijn en wanneer je de tool gebruikt. Zo kan de agent de juiste tool kiezen.

Het USAGE-privilege op een MCP-server stelt een rol in staat om verbinding te maken met de server en de tools ervan te ontdekken. Het geeft de rol geen toegang tot het warehouse, de agent, de semantische weergave, de Search-service, de stored procedure of de onderliggende gegevens. Verleen de rol toegang tot elke resource die de tools van de server nodig hebben.

Verleen alleen toegang tot de aanvullende resources die elke tool nodig heeft. Verleen bijvoorbeeld SELECT op een goedgekeurde semantische weergave, USAGE op een Cortex Search-service of USAGE op een specifieke functie of procedure. Wijs de rol niet toe aan PUBLIC en voeg geen brede privileges toe voor huidige of toekomstige objecten.

Controleer de MCP-server en de bijbehorende rechten voordat je OAuth instelt:

Configureer het MCP-schema om precies de rol bekend te maken die leden moeten aanvragen:

Gebruik een expliciet rolbereik. Gebruik niet session:role:all. Snowflake behandelt die waarde als de standaard primaire rol van de gebruiker, niet als toegang tot elke rol, en beleidsregels voor bevoorrechte rollen kunnen dit blokkeren. Een expliciete rol maakt de aangevraagde toegang duidelijk en gemakkelijker te controleren.

Stem af met de beheerder van je Notion-workspace voordat je deze SQL uitvoert. Vraag de beheerder om de Snowflake-server-URL in te voeren in het MCP-instellingsformulier van de workspace en Authenticatie handmatig configureren en Een gedeelde OAuth-client voor de workspace gebruiken in te schakelen. Notion genereert een redirect-URI. Kopieer die en stuur die naar de Snowflake-beheerder. Zodra Snowflake de client-ID en het secret heeft aangemaakt, kan de workspacebeheerder de verbinding instellen.

Gebruik de redirect-URI precies zoals Notion deze verstrekt. Voeg geen afsluitende slash of queryparameters toe en wijzig de host niet.

Als je IS_AGENTIC = TRUE instelt, worden sessies die via deze integratie zijn aangemaakt gemarkeerd als agentsessies. De Snowflake-functie IS_AGENT_ACTIVATED() retourneert dan TRUE, zodat Snowflake agentspecifieke controles en governance kan toepassen. Gebruik je het optionele model met secundaire rollen? Stel dan OAUTH_USE_SECONDARY_ROLES = IMPLICIT in en laat ALLOWED_ROLES_LIST weg.

De geldigheidsduur van het refresh-token, 7776000 seconden, is 90 dagen. Controleer voordat je deze waarde gebruikt of die past bij het beleid van je organisatie voor herautorisatie en tokenrotatie. Gebruik voor gewone wijzigingen liever niet CREATE OR REPLACE SECURITY INTEGRATION. Als je de integratie vervangt, kunnen bestaande verbindingen worden onderbroken.

Voer het volgende uit om de integratie te controleren zonder het secret weer te geven:

Controleer of de integratie is ingeschakeld, de redirect-URI exact overeenkomt, de rol is toegestaan en niet geblokkeerd, refresh-tokens en PKCE zijn ingeschakeld en zowel het autorisatie- als het token-endpoint de openbare accounthost van Snowflake gebruikt.

Deze stap is alleen nodig als je organisatie een netwerkbeleid vereist. Vraag de verantwoordelijke voor beveiliging of het netwerk om de huidige uitgaande IP-bereiken van Notion goed te keuren.

De OAuth-integratie moet beide Notion-paden toestaan:

1. het API-pad dat OAuth-callbacks afhandelt en autorisatiecodes uitwisselt

2. het runtime-pad van de workspace dat de verbinding valideert, tools uitvoert en tokens ververst

Deze paden kunnen verschillende uitgaande Notion-adressen gebruiken. Als je alleen het adres van de eerste tokenuitwisseling toestaat, kan aanmelden lukken terwijl de validatie of het vernieuwen van tokens mislukt. Gebruik de huidige, goedgekeurde uitgaande IP-bereiken van Notion. Voeg geen eenmalig IP-adres uit een browser of log toe aan een allowlist voor productie.

Koppel dit netwerkbeleid aan de OAuth-integratie, niet aan afzonderlijke gebruikers. Wijzig het accountbrede beleid voor aanmelden via een browser, VPN-toegang of netwerktoegang niet. Als een netwerkbeleid een tokenverzoek blokkeert, kan Snowflake invalid_client retourneren. Dat betekent niet per se dat de client-ID of het secret onjuist is.

Voer dit uit in een beveiligd Snowflake-werkblad. De integratienaam is hoofdlettergevoelig en is meestal in hoofdletters:

Deel de client-ID en het bijbehorende secret met de beheerder van je Notion-workspace via een goedgekeurd, beveiligd kanaal. Snowflake biedt twee geldige secrets, zodat je ze zonder onderbreking kunt roteren. Plak geen van beide secrets in documentatie, chats, tickets of broncodebeheer.

Zodra Snowflake klaar is, voegt een workspace-eigenaar of -beheerder de server één keer toe voor de workspace. Leden kunnen de server dan vinden zonder het OAuth-clientsecret te zien, of ze de Snowflake MCP nu koppelen aan een Aangepaste agent of aan hun eigen Notion-agent.

1. Ga naar Instellingen voor de workspace.

2. Selecteer Koppelingen → Gedeelde MCP's van de workspace.

3. Selecteer Nieuwe workspace-MCP.

Vul deze velden in en selecteer vervolgens MCP-server toevoegen:

Controleer na het opslaan of de nieuwe rij onder Shared with this workspace verschijnt en of Workspace OAuth client de status Configured toont.

Wat deze configuratie doet:

• Helpt leden de goedgekeurde server te vinden.

• Slaat het OAuth-clientsecret eenmalig op in de versleutelde verbindingsopslag van Notion.

• Zorgt ervoor dat leden zich aanmelden met de server-URL, client en bereiken die u hebt goedgekeurd.

• Maakt geen gedeelde Snowflake-sessie aan en omzeilt de toegangscontroles van Snowflake niet.

• Koppelt niet automatisch alle leden. Iedereen moet zich afzonderlijk aanmelden.

Als je deze configuratie verwijdert, kunnen nieuwe leden de server niet meer vinden. Bestaande verbindingen kunnen nog zichtbaar zijn. Stem deze wijziging daarom af op het intrekken van Snowflake-toegangsrechten en het verwijderen van bestaande verbindingen.

Zodra je beheerders de Snowflake-MCP-verbinding hebben ingesteld, kun je die op twee manieren gebruiken. Stel je dit in voor een team? Begin dan bij 11A. Wil je alleen zelf vragen stellen? Ga dan naar 11B. Je kunt ook allebei doen: het zijn aparte verbindingen.

Met een Aangepaste agent kan je team op één plek vragen stellen over Snowflake-gegevens. Je koppelt Snowflake één keer, voegt instructies toe over je statistieken en tabellen en deelt de agent met je team. Iedereen die de agent gebruikt, meldt zich met eigen inloggegevens aan bij Snowflake. Zo krijgt ieder teamlid alleen antwoorden op basis van gegevens waarvoor diegene toegang heeft.

Snowflake koppelen aan een Aangepaste agent

1. Open je Aangepaste agent of maak een nieuwe aan.

2. Ga naar Instellingen → Tools en toegang.

3. Selecteer Verbinding toevoegen en kies vervolgens de Snowflake-server met het label Workspace Managed. Selecteer niet Custom MCP server en voer de server-URL niet handmatig in.

4. Log in bij Snowflake in je browser. Het gebruikelijke Okta- of SSO-inlogscherm van je organisatie kan verschijnen.

5. Controleer en keur de gevraagde Snowflake-rol goed.

6. Kies welke tools de agent mag gebruiken. Laat tools die gegevens kunnen schrijven en CORTEX_AGENT_RUN op 'om goedkeuring vragen' staan totdat je ze hebt getest.

7. Selecteer Koppelen en bevestig dat de verbinding wordt weergegeven als Gekoppeld.

De agent context geven

De koppeling geeft de agent toegang tot Snowflake. Je instructies vertellen de agent hoe je bedrijf die gegevens gebruikt. Beschrijf in de instructies van de agent welke tools voor welke soorten vragen moeten worden gebruikt, hoe je team belangrijke statistieken definieert en van welke tabellen of semantische weergaven moet worden uitgegaan. Een paar geverifieerde voorbeeldvragen helpen enorm. Zie de handleiding voor de Data Scout-toolkit voor een kant-en-klaar startpunt.

De agent delen

Deel de agent met je team zoals je dat met elke Aangepaste agent doet. De eerste keer dat iemand een vraag stelt waarvoor Snowflake nodig is, wordt diegene gevraagd in te loggen met een eigen Snowflake-account. Een client-ID of secret is niet nodig.

Als je je eigen vragen wilt stellen in je eigen chat, koppel dan Snowflake aan je Notion-agent. Je logt in met je eigen Snowflake-account, zodat je agent alleen toegang heeft tot wat jij mag zien.

1. Ga naar Instellingen → Notion AI.

2. Selecteer onder MCP-servers de optie MCP-server toevoegen.

3. Selecteer de Snowflake-server met het label Workspace Managed. Selecteer niet Custom MCP server en voer de server-URL niet handmatig in.

4. Selecteer Koppelen.

5. Log in bij Snowflake in je browser. Het gebruikelijke Okta- of SSO-inlogscherm van je organisatie kan verschijnen.

6. Controleer en keur de gevraagde Snowflake-rol goed.

7. Wanneer je browser vraagt of Notion moet worden geopend, selecteer je Open Notion.

8. Controleer of de serverstatus Gekoppeld is en niet Authenticatie vereist.

Nadat je verbinding hebt gemaakt, verschijnt Snowflake in de chat onder Alle bronnen → MCP-servers.

1. Stel een onschuldige vraag waarop je het antwoord al weet en waarvoor Snowflake nodig is.

2. Controleer of de agent Snowflake gebruikt en een resultaat geeft.

3. Controleer of je geen toegang hebt tot gegevens buiten de rol die je hebt gekregen.

Als je een Aangepaste agent instelt, vraag dan ook een teamgenoot met een beperktere Snowflake-rol om het te proberen. Die zou alleen de eigen gegevens moeten zien, niet die van jou. Dat is de snelste manier om te bevestigen dat de agent de toegang van elke persoon gebruikt in plaats van die van de maker.

Vraag voor een grondigere controle je Snowflake-beheerder om je gebruikersaccount, rol, warehouse en querygeschiedenis te controleren. Als je kunt inloggen, is je identiteit bevestigd, maar dat betekent niet dat al je toegangsrechten kloppen.

Stel de agent een specifieke vraag over je Snowflake-gegevens. Bijvoorbeeld:

• ‘Wat waren volgens Snowflake onze totale aanmeldingen vorige maand?’

• ‘Wat waren volgens Snowflake onze 10 accounts met de hoogste omzet dit kwartaal?’

Bij een Aangepaste agent kun je ‘volgens Snowflake’ meestal weglaten als de instructies duidelijk maken wanneer de agent Snowflake moet gebruiken. Bij je Notion-agent helpt het om Snowflake te noemen, zodat de agent de juiste bron kiest.

Grote verzoeken kunnen langer duren of een time-out veroorzaken. Als dat gebeurt, stel dan een specifiekere vraag of splits het verzoek op in kleinere vragen.

Meestal blijf je verbonden zonder dat je iets hoeft te doen. Snowflake gebruikt kortstondige toegangstokens en Notion ververst deze op de achtergrond. Een verlopend toegangstoken verbreekt de verbinding op zichzelf niet.

Je moet opnieuw inloggen als:

• Je ververstoken verloopt of een beheerder trekt deze in

• Een beheerder vervangt de OAuth-integratie of het clientsecret

• Je Snowflake-rol wordt verwijderd

• Een beheerder verwijdert de workspace-instellingen of je verbinding

• Een netwerkbeleid blokkeert de tokenvernieuwing

Bij een Aangepaste agent logt iedereen apart in. Als iemand opnieuw moet inloggen, heeft dat geen gevolgen voor anderen. De maker van de agent hoeft niets te doen.

Als je het clientsecret vernieuwt: gebruik dan Snowflakes methode met twee secrets in plaats van de integratie te vervangen. Houd beide secrets lang genoeg geldig om de workspace-instellingen bij te werken en te testen voordat je het oude secret intrekt.

ALTER SECURITY INTEGRATION <oauth_integration_name>
REFRESH OAUTH_CLIENT_SECRET_2;

• De Snowflake-MCP-verbinding staat niet in de lijst. Je workspacebeheerder heeft deze mogelijk nog niet toegevoegd, of je workspace beperkt mogelijk aangepaste servers. Vraag je beheerder om hulp.

• Je wordt gevraagd om een client-ID of secret. Je hebt waarschijnlijk de aangepaste MCP-optie gekozen. Ga terug en kies in plaats daarvan de Snowflake-server die is gemarkeerd als Workspace Managed.

• Je wordt gevraagd om opnieuw in te loggen. Je Snowflake-sessie is mogelijk verlopen of een beheerder heeft de verbinding mogelijk bijgewerkt. Log opnieuw in bij Snowflake.

• Je hebt een Aangepaste agent geopend en moet inloggen bij Snowflake. Dat is de eerste keer normaal. Iedereen die een beheerde Aangepaste agent gebruikt, moet met eigen Snowflake-inloggegevens inloggen.

• Een teamgenoot krijgt andere resultaten van dezelfde Aangepaste agent. Dat is normaal. De agent gebruikt ieders eigen Snowflake-toegang. Mensen met verschillende rollen zien dus verschillende gegevens.

• De Aangepaste agent werkt in de chat, maar niet volgens een schema. Bij geplande uitvoeringen en uitvoeringen die door een trigger worden gestart, is niemand ingelogd. Daarom kunnen ze Snowflake nog niet gebruiken met een afzonderlijke aanmelding per persoon.

• Je bent ingelogd, maar er wordt geen verbinding gemaakt of de tools werken niet. Inloggen bevestigt je identiteit, maar je toegang hangt nog steeds af van je Snowflake-rechten. Vraag je Snowflake-beheerder om te bevestigen dat je rol toegang heeft tot de server, het warehouse, de agent en de gegevens.

• De agent kan een tabel niet vinden. De agent kan alleen bij gegevens waartoe je Snowflake-account toegang heeft. Controleer je Snowflake-machtigingen en noem de tabel in je vraag.

• Een verzoek duurt te lang. Stel een specifiekere vraag of splits je verzoek op in kleinere vragen.

Deze fouten komen meestal door Snowflake-instellingen, niet door Notion. Deel ze met je Snowflake-beheerder.

• De server-URL lijkt dubbel, zoals https://https%3A... Het adres is geplakt met een extra https:// ervoor. Corrigeer dit zodat de URL met slechts één https:// begint.

• Je ziet ‘This server does not support OAuth authentication.’ De beveiligingsintegratie is niet ingesteld voor OAuth, of de server-URL klopt niet. Vraag je Snowflake-beheerder om de OAuth-beveiligingsintegratie en de server-URL te controleren.

• Je ziet invalid_client tijdens het inloggen of vernieuwen. De client-ID of het secret klopt niet, of het secret is gewijzigd. Vraag je beheerder om de huidige client-ID en het secret.

• Aanmelden werkt, maar mislukt direct daarna. Je rol bereikt de server mogelijk niet, of een rol- of netwerkregel blokkeert de sessie. Vraag je beheerder om je rechten en beleidsregels te controleren.

• Je ziet ‘The role ALL requested has been explicitly blocked.’ De verbinding vroeg om alle rollen tegelijk (session:role:all), maar dat is geblokkeerd. Gebruik één specifieke rol, zoals session:role:analyst, met je echte rolnaam.

• Je ziet een omleidingsfout (fout 390307). De omleidings-URL in Snowflake komt niet overeen met de URL die Notion gebruikt. Vraag je beheerder om de omleidings-URL in de beveiligingsintegratie in te stellen op precies de URL van Notion.

• Je ziet fout 390311 over een ongeldige code challenge. De PKCE-instellingen komen niet overeen. Vraag je beheerder te controleren of OAUTH_ENFORCE_PKCE goed is ingesteld in de beveiligingsintegratie.

• Je bent verbonden, maar je ziet geen tools. Je rol heeft mogelijk geen USAGE-recht op de MCP-server. Vraag je beheerder dit te controleren en voer daarna DESCRIBE MCP SERVER uit om de configuratie te controleren.

• Je hebt toegang tot meer of minder gegevens dan verwacht. Secundaire rollen bepalen mede welke gegevens je in je sessie kunt zien. Controleer samen met je beheerder welke rollen in je sessie actief zijn.

• Eerder werkte het, maar na een wijziging van een secret lukt het bij niemand meer. Het clientsecret is vernieuwd, dus de opgeslagen verbinding is verouderd. Vraag je beheerder om het nieuwe secret en maak opnieuw verbinding.

• Eerder werkte het, maar nu lukt het alleen bij jou niet meer. Een rol, recht of beleidsregel is mogelijk gewijzigd, of je sessie is verlopen. Meld je opnieuw aan en vraag je beheerder te controleren of je toegang is veranderd.

• Je account-id wordt geweigerd. Gebruik de indeling organization-account met een koppelteken, zoals myorg-myaccount, en niet met punten.

• Een PrivateLink-account kan geen verbinding maken. PrivateLink-accounts hebben extra netwerkinstellingen nodig. Vraag je beheerder of PrivateLink de verbinding met Notion toestaat.

• Snowflake is niet beschikbaar in geplande of door een trigger gestarte uitvoeringen. Bij die uitvoeringen is niemand aangemeld, dus aanmelden per persoon werkt daar nog niet. Voer je verzoek in plaats daarvan uit in de chat.

• Je ziet oauth_security_error nadat je je via de browser hebt aangemeld. Een netwerkbeleid op accountniveau blokkeert mogelijk het verzoek. Je beheerder kan dit controleren door het volgende uit te voeren:

• Aanmelden lijkt te werken, maar je krijgt een foutmelding over je rol, zelfs met de juiste scope. Je standaardrol is mogelijk geblokkeerd, bijvoorbeeld ACCOUNTADMIN of een rol in BLOCKED_ROLES_LIST. Je beheerder kan dit controleren en oplossen:

Met deze opdrachten kan je beheerder de configuratie controleren zonder iets te wijzigen. Voer ze uit in Snowflake.

Gebruik deze Snowflake-handleidingen om de configuratie te voltooien:

• Door Snowflake beheerde MCP-server

• Een Snowflake OAuth-beveiligingsintegratie maken

• Snowflake OAuth voor aangepaste clients

• Overzicht van Snowflake OAuth

• Snowflake-account-id's

• Aangepaste agents

• MCP-koppelingen voor Aangepaste agents

• MCP-servers koppelen aan je Notion-agent

• Aanbevolen werkwijzen voor veilige agentkoppelingen