De Snowflake MCP voor Notion instellen

Je kunt je Aangepaste agents en Notion-agent via een door Snowflake beheerde MCP (Model Context Protocol)-server koppelen aan Snowflake. Zodra alles is ingesteld, kun je je agent vragen stellen over de gegevens in je Snowflake-warehouse en direct antwoord 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-koppeling voor de workspace.

• Workspaceleden kunnen vervolgens vanuit Aangepaste agents met hun eigen Snowflake-inloggegevens verbinding maken met de Snowflake-MCP, of Snowflake rechtstreeks koppelen aan hun Notion-agent. Stappen 1–10 van dit artikel zijn hetzelfde voor beide opties. Vanaf stap 11 verschillen de stappen, 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 op het Chinese vasteland of in overheidsregio's.

• Je Notion-workspace heeft een Business- of Enterprise-abonnement nodig.

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

• Je bedrijf heeft een Snowflake-account nodig.

• Je hebt een machtiging nodig om agents in je workspace aan te maken voordat je een Aangepaste agent kunt bouwen.

Voordat je team Snowflake aan Notion kan koppelen, moet een Snowflake-beheerder de toegang instellen. Dit kost het meeste werk, maar hoeft maar één keer. Werk samen met je Notion-workspacebeheerder: Notion levert een redirect-URI en Snowflake een OAuth-client-ID en een 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 onderstrepingstekens. Zorg dat elke objectnaam in de server-URL overeenkomt met de bijbehorende naam in Snowflake.

Gebruik waar mogelijk een aparte 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 als de server rechten nodig heeft die gebruikers via hun Snowflake-rollen DEFAULT_SECONDARY_ROLES krijgen. Stel OAUTH_USE_SECONDARY_ROLES = IMPLICIT in, laat ALLOWED_ROLES_LIST weg en gebruik een expliciet bereik voor de primaire rol. Snowflake staat secundaire rollen met IMPLICIT niet toe in combinatie met ALLOWED_ROLES_LIST. Laat de lijst met toegestane rollen dus weg als je dit model gebruikt.

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

Ken deze rol toe via je gebruikelijke proces voor identiteitsbeheer. Als Okta of SCIM bepaalt wie welke Snowflake-rol heeft, 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 beheerde zakelijke vragen kun je een Cortex Agent beschikbaar stellen als tool voor leden. Deze brengt semantische weergaven, geverifieerde query's, Snelzoeken en orkestratie op één plek samen. Een Cortex Agent is optioneel. Maak je er een aan, gebruik dan de onderstaande specificatie. Vervang je een bestaande agent, zorg dan dat de nieuwe aan je goedgekeurde specificatie voldoet.

Andere ondersteunde Snowflake-MCP-tooltypen zijn 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 weergave, de Snelzoeken-service, de opgeslagen 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 zodat het de exacte rol vermeldt 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 URL van de Snowflake-server in te voeren in het MCP-instellingsformulier van de workspace en Authenticatie handmatig configureren en Een door de workspace gedeelde OAuth-client gebruiken in te schakelen. Notion genereert een redirect-URI. Kopieer die en stuur hem naar de Snowflake-beheerder. Nadat Snowflake de client-ID en het secret heeft aangemaakt, kan de workspacebeheerder de verbinding verder instellen.

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

Met IS_AGENTIC = TRUE worden sessies die via deze integratie worden aangemaakt, gemarkeerd als agentsessies. De Snowflake-functie IS_AGENT_ACTIVATED() retourneert dan TRUE. 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.

Een geldigheidsduur van 7776000 seconden voor het refresh-token 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 geen 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:

Bevestig dat de integratie is ingeschakeld, de redirect-URI exact overeenkomt, de rol is toegestaan en niet geblokkeerd, refresh-tokens en PKCE zijn ingeschakeld, en zowel de autorisatie- als token-endpoints de openbare account-host 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 uitgaande IP-adressen van Notion gebruiken. Als je alleen het adres toestaat dat bij de eerste tokenuitwisseling is gebruikt, lukt aanmelden misschien wel, maar kunnen de validatie en het vernieuwen van tokens mislukken. Gebruik de huidige, goedgekeurde IP-bereiken voor uitgaand verkeer van Notion. Voeg geen IP-adres dat je eenmalig in een browser of log ziet toe aan een toelatingslijst voor productie.

Koppel dit netwerkbeleid aan de OAuth-integratie, niet aan afzonderlijke gebruikers. Wijzig niet het beleid voor het hele account voor aanmelden via de browser, VPN-toegang of netwerktoegang voor gebruikers. Als een netwerkbeleid een tokenverzoek blokkeert, kan Snowflake invalid_client retourneren. Deze fout 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 via een goedgekeurd beveiligd kanaal met de beheerder van je Notion-workspace. Snowflake biedt twee geldige secrets, zodat je ze kunt vervangen zonder onderbreking. Plak geen van beide secrets in documentatie, chats, tickets of broncodebeheer.

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

1. Ga naar Instellingen voor de workspace.

2. Selecteer Koppelingen → Workspace shared MCPs.

3. Selecteer Nieuwe workspace-MCP.

Vul deze velden in en selecteer 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, de client en de bereiken die je hebt goedgekeurd.

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

• Verbindt 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 wel zichtbaar blijven. Stem het verwijderen 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 voor een team in? Begin dan bij 11A. Wil je alleen zelf vragen stellen? Ga dan naar 11B. Je kunt ook beide doen: het zijn afzonderlijke 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 meetwaarden en tabellen en deelt de agent met je team. Iedereen die de agent gebruikt, moet zich met eigen inloggegevens aanmelden bij Snowflake. 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 vervolgens de Snowflake-server met het label Workspace Managed. Selecteer niet Aangepaste 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. Select Koppelen en controleer of de verbinding als Gekoppeld wordt weergegeven.

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, moet diegene inloggen met een eigen Snowflake-account. Er wordt niet om een client-ID of secret gevraagd.

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. Select de Snowflake-server met het label Workspace Managed. Select niet Custom MCP server en voer de server-URL niet handmatig in.

4. Select 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, kies 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 waartoe de rol die je hebt gekregen geen toegang geeft.

Als je een Aangepaste agent instelt, vraag dan ook een teamgenoot met een beperktere Snowflake-rol om het te proberen. Die teamgenoot hoort alleen de eigen gegevens te zien, niet die van jou. Zo controleer je snel of de agent de toegang van elke gebruiker 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:

• "Hoeveel aanmeldingen hadden we volgens Snowflake in totaal vorige maand?"

• "Welke 10 accounts hadden volgens Snowflake dit kwartaal de hoogste omzet?"

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 ververstoken verloopt of een beheerder trekt het in

• Een beheerder vervangt de OAuth-integratie of het clientsecret

• Je Snowflake-rol wordt verwijderd

• Een beheerder verwijdert de workspace-instelling of je verbinding

• Een netwerkbeleid blokkeert de tokenvernieuwing

Bij een aangepaste agent is de aanmelding van elke persoon afzonderlijk. Als aan één persoon wordt gevraagd om opnieuw in te loggen, heeft dit geen invloed op anderen en hoeft de persoon die de agent heeft gebouwd niets te doen.

Als je het clientsecret vervangt: Gebruik Snowflakes methode met twee secrets in plaats van de integratie te vervangen. Laat 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 workspacebeheerder heeft die mogelijk nog niet toegevoegd, of je workspace staat aangepaste servers niet toe. Vraag je beheerder om hulp.

• Je wordt gevraagd om een client-ID of secret. Je hebt waarschijnlijk de optie voor een aangepaste MCP-server gekozen. Ga terug en kies de Snowflake-server met het label 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 die vroeg je om in te loggen bij Snowflake. Dat is normaal als je de agent voor het eerst gebruikt. Iedereen die een beheerde Aangepaste agent gebruikt, moet inloggen met eigen Snowflake-inloggegevens.

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

• De Aangepaste agent werkt in de chat, maar niet volgens een schema. Geplande uitvoeringen en uitvoeringen die door een trigger worden gestart, hebben geen ingelogde gebruiker. Daarom kunnen ze Snowflake nog niet gebruiken met individuele aanmeldingen.

• 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 heeft alleen toegang tot de gegevens die je Snowflake-account kan bereiken. 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 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 werkelijke rolnaam.

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

• Je ziet fout 390311 over een ongeldige code challenge. Dit is een PKCE-mismatch. Vraag je beheerder om te controleren of OAUTH_ENFORCE_PKCE goed is ingesteld in de beveiligingsintegratie.

• Je bent verbonden, maar ziet geen tools. Je rol heeft mogelijk geen USAGE op de MCP-server. Vraag je beheerder om 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 je verwachtte. Secundaire rollen bepalen mede wat je sessie kan zien. Controleer samen met je beheerder welke rollen actief zijn in je sessie.

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

• Het werkte eerst, maar nu werkt het alleen voor jou niet meer. Een rol, recht of beleid is mogelijk gewijzigd, of je sessie is verlopen. Meld je opnieuw aan en vraag je beheerder om te controleren of je toegang niet is gewijzigd.

• 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. PrivateLink-accounts vereisen extra netwerkconfiguratie. Vraag je beheerder of PrivateLink de Notion-verbinding toestaat.

• Snowflake is niet beschikbaar bij geplande uitvoeringen of uitvoeringen via een trigger. 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 na het aanmelden via de browser. Een netwerkbeleid op accountniveau blokkeert mogelijk het verzoek. Je beheerder kan dit controleren met:

• Aanmelden lijkt te werken, maar je krijgt een rolfout, 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:

Deze opdrachten met alleen leestoegang helpen je beheerder de configuratie te 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-accountidentificaties

• Aangepaste agents

• MCP-koppelingen voor Aangepaste agents

• MCP-servers koppelen aan je Notion-agent

• Aanbevolen beveiligingsmaatregelen voor agentkoppelingen