De Snowflake MCP voor Notion instellen

Je Aangepaste agenten en Notion-agent kunnen via een MCP (Model Context Protocol)-server van Snowflake 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 een 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 opties hetzelfde. Vanaf stap 11 kies je de stappen voor de agent die 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 op het web of op je computer. Deze functie is niet beschikbaar op mobiel.

• Je bedrijf heeft een Snowflake-account nodig.

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

Voordat je team Snowflake aan Notion kan koppelen, moet een Snowflake-beheerder de toegang instellen. Dit is de grootste stap, maar je hoeft hem maar één keer te doen. Werk samen met je Notion-workspacebeheerder: Notion levert een redirect-URI en Snowflake een OAuth-client-ID en -secret.

Je stelt een rol en warehouse in, maakt de door Snowflake beheerde MCP-server aan, geeft die toegang tot de benodigde resources, configureert het OAuth-bereik en de beveiligingsintegratie en voegt zo nodig een netwerkbeleid toe.

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.

Beperkte rol zonder secundaire rollen (aanbevolen). 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>.

De standaard secundaire rollen van een gebruiker (optioneel). Gebruik dit model alleen wanneer de server rechten nodig heeft die voortvloeien uit de DEFAULT_SECONDARY_ROLES van elke Snowflake-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 wanneer 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 toegangsbeheer kun je een Cortex Agent aanbieden als tool voor leden. Die houdt semantische views, geverifieerde query's, Snelzoeken en orkestratie bij elkaar. Een Cortex Agent is niet verplicht. Maak je er een aan? Gebruik dan de specificatie hieronder. Vervang je een bestaande agent? Zorg dan dat de nieuwe aan je 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 deze dekt, hoe gedetailleerd de resultaten zijn en wanneer deze moet worden gebruikt. Dit helpt de agent om de juiste tool te 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 view, 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 view, 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:

Stel het MCP-schema zo in dat het precies de rol aangeeft 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.

Overleg 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 verder instellen.

Gebruik de redirect-URI precies zoals Notion die geeft. Voeg geen slash aan het einde of queryparameters toe en verander de host niet.

Met IS_AGENTIC = TRUE markeer je sessies die via deze integratie worden aangemaakt als agentsessies. De Snowflake-functie IS_AGENT_ACTIVATED() geeft dan TRUE terug. Zo kan Snowflake agentspecifieke controles en governance 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 is 7776000 seconden, oftewel 90 dagen. Controleer voordat je deze waarde gebruikt of die past bij het beleid van je organisatie voor herautorisatie en tokenrotatie. Gebruik bij gewone wijzigingen liever niet CREATE OR REPLACE SECURITY INTEGRATION: als je de integratie vervangt, kunnen bestaande verbindingen worden onderbroken.

Controleer de integratie zonder het secret weer te geven met:

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 beide endpoints voor autorisatie en tokens de openbare accounthost van Snowflake gebruiken.

Deze stap is alleen nodig als je organisatie een netwerkbeleid vereist. Vraag de verantwoordelijke voor beveiliging of het netwerk om de huidige IP-bereiken voor uitgaand verkeer 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 IP-adressen van Notion gebruiken voor uitgaand verkeer. Sta je alleen het adres van de eerste tokenuitwisseling toe, dan lukt aanmelden misschien wel, maar kunnen validatie en tokenverversing mislukken. Gebruik de huidige, goedgekeurde IP-bereiken voor uitgaand verkeer van Notion. Voeg geen eenmalig IP-adres uit een browser of log toe aan een lijst met toegestane productie-IP-adressen.

Koppel dit netwerkbeleid aan de OAuth-integratie, niet aan afzonderlijke gebruikers. Verander het beleid voor het hele account rond aanmelden via de browser, VPN-toegang of netwerktoegang voor gebruikers niet. Blokkeert een netwerkbeleid een tokenverzoek, dan kan Snowflake invalid_client teruggeven. Dat betekent niet automatisch 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 vervangen. Plak geen van beide secrets in documentatie, chats, tickets of versiebeheer.

Zodra Snowflake klaar is, voegt een eigenaar of beheerder de server één keer toe voor de workspace. Daarna kunnen leden de server vinden zonder het OAuth-clientsecret te zien. Dat geldt zowel voor een koppeling tussen Snowflake MCP en een Aangepaste agent als voor een koppeling met hun eigen Notion-agent.

1. Ga in je workspace naar Instellingen.

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

3. Selecteer Nieuwe workspace-MCP.

Vul deze velden in en selecteer MCP-server toevoegen:

Controleer na het opslaan of de nieuwe rij onder Gedeeld met deze workspace staat en of bij OAuth-client van de workspace de status Geconfigureerd staat.

Wat deze configuratie doet:

• Leden helpen de goedgekeurde server te vinden

• Het OAuth-clientsecret één keer opslaan in de versleutelde opslag voor verbindingen van Notion

• Zorgen dat leden zich aanmelden met de server-URL, client en bereiken die je hebt goedgekeurd

• Geen gedeelde Snowflake-sessie aanmaken of de toegangscontroles van Snowflake omzeilen

• Niet automatisch alle leden verbinden. 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 met het intrekken van Snowflake-machtigingen 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 beide 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, moet zich met eigen inloggegevens bij Snowflake aanmelden. Zo krijgt iedereen alleen antwoorden op basis van gegevens waartoe 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 de Snowflake-server met het label Beheerd door de workspace. Selecteer niet Aangepaste MCP-server en voer de server-URL niet zelf 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 elke Aangepaste agent deelt. De eerste keer dat iemand een vraag stelt waarvoor Snowflake nodig is, wordt diegene gevraagd in te loggen met een eigen Snowflake-account. Er wordt niet gevraagd om een client-ID of secret.

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. Bevestig dat de serverstatus Verbonden is, niet Authenticatie vereist.

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

1. Stel een onschadelijke vraag met een bekend antwoord waarvoor Snowflake gebruikt zou moeten worden.

2. Bevestig dat de agent Snowflake gebruikt en een resultaat teruggeeft.

3. Controleer of je geen toegang hebt tot gegevens buiten je toegewezen rol.

Als je een Aangepaste agent instelt, vraag dan ook een teamgenoot met een beperktere Snowflake-rol om die te proberen. Die teamgenoot mag alleen de eigen gegevens zien, niet die van jou. Zo controleer je snel of de agent ieders eigen toegangsrechten gebruikt in plaats van die van de maker.

Vraag voor een grondigere controle je Snowflake-beheerder om je gebruiker, rol, warehouse en querygeschiedenis te bevestigen. Een succesvolle aanmelding bevestigt je identiteit, maar bevestigt niet dat elke toekenning correct is.

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 zodra de instructies duidelijk maken wanneer Snowflake gebruikt moet worden. 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 vernieuwingstoken verloopt of een beheerder trekt het in

• Een beheerder vervangt de OAuth-integratie of het client-secret

• Je Snowflake-rol wordt verwijderd

• Een beheerder verwijdert de workspace-instelling of je verbinding

• Een netwerkbeleid blokkeert de tokenvernieuwing

Bij een Aangepaste agent staat de aanmelding van elke persoon los van die van anderen. Als iemand opnieuw moet inloggen, heeft dat geen gevolgen voor anderen en hoeft de maker van de agent niets te doen.

Als je het client-secret roteert: Gebruik Snowflakes methode met twee secrets in plaats van de integratie te vervangen. Houd beide secrets lang genoeg geldig om de workspace-instelling 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 workspace-beheerder heeft deze mogelijk nog niet toegevoegd, of je workspace staat aangepaste servers mogelijk niet toe. 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 met het label Workspace Managed.

• Je wordt gevraagd 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 die vroeg je om in te loggen 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 de Snowflake-toegang van elke persoon, dus mensen met verschillende rollen zien verschillende gegevens.

• De Aangepaste agent werkt in de chat, maar niet volgens een schema. Geplande uitvoeringen en uitvoeringen op basis van triggers hebben geen ingelogde gebruiker en kunnen Snowflake daarom nog niet gebruiken met individuele aanmelding.

• 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 controleren of je rol toegang heeft tot de server, het warehouse, de agent en de gegevens.

• De agent kan een tabel niet vinden. De agent heeft alleen toegang tot gegevens waartoe je Snowflake-account toegang heeft. Controleer je Snowflake-machtigingen en noem de tabelnaam 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. Zorg dat 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 is onjuist. 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 is onjuist, of het secret is gewijzigd. Vraag je beheerder om de huidige client-ID en het secret.

• Aanmelden werkt, maar mislukt direct daarna. Je rol kan de server mogelijk niet bereiken, 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 die in Snowflake is opgeslagen, 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 die Notion gebruikt.

• 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 voor de MCP-server. Vraag je beheerder dit recht 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 sessie kan zien. Controleer samen met je beheerder welke rollen actief zijn in je sessie.

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

• Eerder werkte het, maar nu werkt het alleen voor jou niet meer. Een rol, recht of beleidsregel kan zijn gewijzigd, of je sessie is verlopen. Meld je opnieuw aan en vraag je beheerder te controleren of je toegangsrechten zijn veranderd.

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

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

• Snowflake is niet beschikbaar voor geplande uitvoeringen of uitvoeringen die door een trigger zijn gestart. Bij deze uitvoeringen is niemand aangemeld, dus aanmelden per persoon werkt hier 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 met:

• Aanmelden lijkt te werken, maar je krijgt een rolfout, ook 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 beveiligingsintegratie voor Snowflake OAuth maken

• Snowflake OAuth voor aangepaste clients

• Overzicht van Snowflake OAuth

• Snowflake-account-id's

• Aangepaste agents

• MCP-koppelingen voor Aangepaste agents

• Koppel MCP-servers aan je Notion-agent

• Tips voor veilige agentkoppelingen