De Snowflake MCP voor Notion instellen

Je Aangepaste agenten en Notion Agent kunnen verbinding maken met Snowflake via een MCP (Model Context Protocol)-server die door Snowflake wordt beheerd. 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 Notion-workspace-eigenaar of -beheerder configureert de Snowflake MCP-verbinding voor de workspace.

• Workspace-leden kunnen vervolgens verbinding maken met de Snowflake MCP vanuit Custom Agents met hun eigen Snowflake-inloggegevens, of Snowflake direct koppelen met hun Notion Agent. Stappen 1–10 van dit artikel zijn hetzelfde voor beide paden. De paden 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 op het Business-abonnement of Enterprise-abonnement zitten.

• Gebruik Notion op het web of op desktop. Deze functie is niet beschikbaar op mobiel.

• Je bedrijf heeft een Snowflake-account nodig.

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

Voordat je team Snowflake met Notion kan koppelen, 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 toegewijde, minst bevoorrechte rol 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 privileges nodig heeft die zijn overgenomen van de DEFAULT_SECONDARY_ROLES van elke gebruiker in Snowflake. Stel OAUTH_USE_SECONDARY_ROLES = IMPLICIT in, laat ALLOWED_ROLES_LIST weg en gebruik een expliciet primair-rolbereik. Snowflake staat geen IMPLICIT secundaire rollen toe met ALLOWED_ROLES_LIST, dus laat de allowlist weg wanneer je dit model gebruikt.

Gebruik waar mogelijk een toegewijde, minst bevoorrechte rol voor de MCP-server.

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

Maak of kies een database en schema die eigendom zijn van het team dat verantwoordelijk is voor de uitvoering van de server.

Voor beheerde zakelijke vragen kun je een Cortex Agent beschikbaar stellen als de tool die leden gebruiken. Het houdt semantische views, geverifieerde query's, Search en orkestratie op één plek. Een Cortex Agent is optioneel. Als je er een maakt, gebruik dan de onderstaande specificatie. Als je een bestaande agent vervangt, zorg er dan voor dat de vervanging overeenkomt met je goedgekeurde specificatie.

Andere ondersteunde Snowflake MCP-tooltypen 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 weergave, de Search service, stored procedure of 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 de exacte rol te adverteren die leden moeten aanvragen:

Gebruik een expliciete rolscope. Gebruik niet session:role:all. Snowflake beschouwt 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 je Notion-werkruimtebeheerder voordat je deze SQL uitvoert. Vraag hen om de Snowflake-server URL in te voeren in het MCP-setupformulier van de werkruimte en Manually configure authentication en Use a workspace-shared OAuth client in te schakelen. Notion genereert een redirect-URI. Kopieer deze en stuur ze naar de Snowflake-beheerder. Nadat Snowflake de client-ID en de secret heeft aangemaakt, kan de werkruimtebeheerder de verbinding voltooien.

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

Het instellen van IS_AGENTIC = TRUE markeert sessies die via deze integratie zijn gemaakt als agentsessies. De IS_AGENT_ACTIVATED()-functie van Snowflake retourneert vervolgens TRUE, waardoor Snowflake agentspecifieke auditing en governance kan toepassen. Als je het optionele secundaire-rolmodel gebruikt, stel je OAUTH_USE_SECONDARY_ROLES = IMPLICIT in en laat je ALLOWED_ROLES_LIST weg.

De geldigheidsduur van het refresh-token van 7776000 seconden komt overeen met 90 dagen. Controleer voordat je het gebruikt of dit overeenkomt met het beleid van je organisatie voor herautorisatie en tokenrotatie. Voor routinematige wijzigingen, vermijd CREATE OR REPLACE SECURITY INTEGRATION. Het vervangen van de integratie kan bestaande verbindingen onderbreken.

Voer het volgende uit om de integratie te controleren zonder de 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 je beveiligings- of netwerkbeheerder om Notion's huidige uitgaande adressen 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 werkruimte dat de verbinding valideert, tools uitvoert en tokens ververst

Deze paden kunnen verschillende uitgaande Notion-adressen gebruiken. Als u alleen het adres toestaat dat tijdens de initiële tokenuitwisseling is gebruikt, kan het inloggen slagen, maar kan validatie of tokenverversing mislukken. Gebruik de huidige, goedgekeurde uitgaande adressen van Notion. Voeg geen eenmalig IP-adres uit een browser of log toe aan een productie-toegestane lijst.

Koppel dit netwerkbeleid aan de OAuth-integratie, niet aan individuele gebruikers. Wijzig je accountbrede beleid voor browser-aanmelding, VPN-toegang of netwerktoegang voor gebruikers niet. Als een netwerkbeleid een tokenverzoek blokkeert, kan Snowflake invalid_client retourneren. Deze fout betekent niet noodzakelijkerwijs dat de client-ID of het geheim 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 uw Notion-workspacebeheerder via een goedgekeurd beveiligd kanaal. Snowflake biedt twee geldige secrets, zodat u ze kunt roteren zonder downtime. Plak nooit een secret in documentatie, chat, tickets of bronbeheer.

Zodra Snowflake gereed is, voegt een workspace-eigenaar of -beheerder de server eenmalig toe voor de workspace. Leden kunnen deze vervolgens vinden zonder het OAuth-client secret te zien, of ze nu de Snowflake MCP koppelen met een Custom Agent of met hun eigen Notion Agent.

1. Ga naar Settings van je workspace.

2. Selecteer Connections → Gedeelde workspace-MCP's.

3. Selecteer Nieuwe workspace-MCP.

Vul deze velden in en selecteer vervolgens Add MCP server:

Nadat u hebt opgeslagen, controleert u of de nieuwe rij onder Gedeeld met deze 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-client secret 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.

• Verbindt niet automatisch elk lid. Elk lid moet zich afzonderlijk aanmelden.

Als u deze configuratie verwijdert, kunnen nieuwe leden de server niet meer vinden. Bestaande verbindingen kunnen nog steeds zichtbaar zijn, dus stem deze wijziging af op het intrekken van Snowflake grants en het verwijderen van bestaande verbindingen.

Zodra je beheerders de Snowflake MCP-verbinding gereed hebben, zijn er twee manieren om deze te gebruiken. Als je dit voor een team instelt, begin dan met 11A. Als je alleen je eigen vragen wilt stellen, ga dan naar 11B. Je kunt beide doen; het zijn afzonderlijke verbindingen.

Een Aangepaste agent geeft uw team één plek om vragen te stellen over Snowflake-gegevens. U koppelt Snowflake één keer, voegt instructies toe over uw statistieken en tabellen, en deelt de agent met uw team. Iedereen die de agent gebruikt, moet inloggen bij Snowflake met eigen inloggegevens, zodat iedereen alleen antwoorden krijgt op basis van de gegevens die zij mogen zien.

Snowflake koppelen aan Aangepaste agent

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

2. Ga naar Instellingen → Tools & 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. De gebruikelijke Okta- of SSO-inlogprocedure 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.

Geef de agent context

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 Data Scout-toolkitgids voor een kant-en-klaar startpunt.

Deel de agent

Deel de agent met je team op dezelfde manier als waarop je elke aangepaste agent deelt. De eerste keer dat iemand een vraag stelt waarvoor Snowflake nodig is, wordt diegene gevraagd om in te loggen met een eigen Snowflake-account. Er wordt niet gevraagd om een client-ID of client secret.

Als je je eigen vragen wilt stellen in je eigen chat, koppel je 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 Aangepaste MCP-server of voer de server-URL niet handmatig in.

4. Selecteer Koppelen.

5. Log in bij Snowflake in je browser. De gebruikelijke Okta- of SSO-inlogprocedure 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 en niet Authenticatie vereist.

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

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

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

3. Bevestig dat 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. Zij zouden alleen hun eigen gegevens moeten zien, niet de jouwe. Dat is de snelste manier om te bevestigen dat de agent de toegang van iedere persoon gebruikt in plaats van die van de bouwer.

Vraag voor een grondigere controle aan 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 onze totale aanmeldingen vorige maand vanuit Snowflake?"

• "Wat waren onze 10 accounts met de hoogste omzet dit kwartaal vanuit Snowflake?"

Bij een aangepaste agent kun je "vanuit Snowflake" meestal weglaten zodra de instructies duidelijk maken wanneer deze moet worden gebruikt. Bij je Notion-agent helpt het benoemen van Snowflake de agent om de juiste bron te kiezen.

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 toegangstokens met een korte levensduur en Notion ververst deze op de achtergrond. Een toegangstoken dat verloopt, zorgt er op zichzelf niet voor dat de verbinding wordt verbroken.

Je moet opnieuw inloggen als:

• Je refresh-token verloopt of een beheerder deze intrekt.

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

• Je Snowflake-rol wordt verwijderd

• Een beheerder verwijdert de werkruimte-instelling of je verbinding.

• Een netwerkbeleid blokkeert de tokenvernieuwing

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

Als je de client secret roteert: Gebruik Snowflake's tweesecret-rotatie 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 de oude intrekt.

ALTER SECURITY INTEGRATION <oauth_integration_name>
REFRESH OAUTH_CLIENT_SECRET_2;

• De Snowflake MCP-verbinding staat niet in de lijst. Je werkruimtebeheerder heeft deze mogelijk nog niet toegevoegd, of je werkruimte 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 bijgewerkt. Log opnieuw in op Snowflake.

• Je opende een aangepaste agent en deze vroeg je om in te loggen bij Snowflake. Dat is normaal bij de eerste keer. Iedereen die een beheerde aangepaste agent gebruikt, moet inloggen met hun eigen Snowflake-inloggegevens.

• 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 op schema. Geplande en getriggerde uitvoeringen hebben geen ingelogde persoon, dus ze kunnen nog geen gebruikmaken van Snowflake met inloggen per persoon.

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

• De agent kan een tabel niet vinden. De agent kan alleen de gegevens bereiken die je Snowflake-account kan bereiken. Controleer je Snowflake-machtigingen en voeg de tabelnaam toe aan je vraag.

• Een verzoek verloopt door een time-out. Stel een specifiekere vraag of splits je verzoek op in kleinere vragen.

Deze fouten komen meestal voort uit Snowflake-instellingen, niet uit 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 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 de secret is onjuist, of de secret is gewijzigd. Vraag je beheerder om de huidige client-ID en de 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), wat geblokkeerd is. Gebruik in plaats daarvan éé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 Notion-waarde.

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

• Je bent verbonden, maar er verschijnen geen tools. Je rol mist mogelijk USAGE op de MCP-server. Vraag je beheerder om het recht te bevestigen en voer vervolgens DESCRIBE MCP SERVER uit om de configuratie te controleren.

• Je kunt meer of minder gegevens bereiken dan je verwacht. Secundaire rollen veranderen wat je sessie kan zien. Controleer samen met je beheerder welke rollen actief zijn in je sessie.

• Het werkte voorheen, en nu mislukt het voor iedereen na een wijziging van een secret. Het client secret was geroteerd, dus de opgeslagen verbindingen zijn verouderd. Vraag je beheerder om de nieuwe secret en maak vervolgens opnieuw verbinding.

• Het werkte voorheen, en nu mislukt het alleen voor jou. Een rol, recht of beleid is mogelijk gewijzigd, of je sessie is verlopen. Meld je opnieuw aan en vraag je beheerder om te bevestigen dat je toegang niet is gewijzigd.

• Je account identifier wordt geweigerd. Gebruik de indeling organization-account met een koppelteken, zoals myorg-myaccount, 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 in geplande of getriggerde runs. Die runs hebben geen aangemelde persoon, dus ze kunnen nog geen gebruikmaken van per-persoonsaanmelding. 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 blokt mogelijk het verzoek. Je beheerder kan dit bevestigen door het volgende uit te voeren:

• Aanmelden lijkt te werken, maar je krijgt een rolfout, zelfs met het juiste bereik. Je standaardrol is mogelijk geblokkeerd, bijvoorbeeld ACCOUNTADMIN of een rol in BLOCKED_ROLES_LIST. Je beheerder kan dit controleren en herstellen:

Deze alleen-lezen opdrachten helpen je beheerder de configuratie te bevestigen 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 agenten

• MCP-koppelingen voor Aangepaste agenten

• Verbind MCP-servers met je Notion-agent

• Best practices voor beveiliging van agentkoppelingen