Configura l'MCP di Snowflake per Notion

I tuoi agenti personalizzati e il tuo agente di Notion possono connettersi a Snowflake tramite un server MCP (Model Context Protocol) eseguito da Snowflake. Una volta configurato, puoi porre domande al tuo agente sui dati del tuo warehouse Snowflake e ottenere risposte direttamente in Notion.

La configurazione avviene in più fasi e ogni fase ha un responsabile diverso:

• Un amministratore Snowflake configura il ruolo, il warehouse e il server MCP gestito da Snowflake.

• Un proprietario dello spazio di lavoro Notion o un amministratore configura la connessione MCP di Snowflake per lo spazio di lavoro.

• I membri dello spazio di lavoro possono quindi connettersi all'MCP di Snowflake dagli agenti personalizzati utilizzando le proprie credenziali Snowflake, oppure connettere Snowflake direttamente al proprio agente di Notion. I passaggi da 1 a 10 di questo articolo sono identici per entrambi i percorsi. I percorsi si dividono al passaggio 11, a seconda dell'agente che desideri connettere.

• Gli strumenti disponibili possono variare in base alla tua regione cloud Snowflake.

• Il server MCP gestito da Snowflake non è disponibile nella Cina continentale o nelle regioni governative.

• Il tuo spazio di lavoro Notion deve avere un piano Business o Enterprise.

• Usa Notion sul web o su desktop. Questa funzionalità non è disponibile su dispositivi mobili.

• La tua azienda deve disporre di un account Snowflake.

• Per creare un agente personalizzato, devi avere l'autorizzazione per creare agenti nel tuo spazio di lavoro.

Prima che il tuo team possa connettere Snowflake a Notion, un amministratore Snowflake deve configurare l'accesso. Questo è il passaggio più complesso e devi eseguirlo solo una volta. Collabora con l'amministratore del tuo spazio di lavoro Notion: Notion fornisce un URI di reindirizzamento e Snowflake fornisce un ID client OAuth e un segreto.

Configurerai un ruolo e un warehouse, creerai il server MCP gestito da Snowflake, gli concederai l'accesso alle risorse necessarie, configurerai l'ambito OAuth e l'integrazione di sicurezza e aggiungerai una policy di rete se la tua organizzazione ne richiede una.

Compila questo foglio di lavoro con l'amministratore del tuo spazio di lavoro Notion prima di iniziare. I membri possono saltarlo e accedere con i propri account Snowflake una volta completata la configurazione.

Il nome host dell'account usa trattini, non trattini bassi. Assicurati che i nomi degli oggetti nell'URL del server corrispondano a quelli in Snowflake.

Utilizza un ruolo dedicato con privilegi minimi e un warehouse approvato ogni volta che è possibile.

Ruolo limitato senza ruoli secondari (consigliato). Questo modello è più facile da comprendere e controllare. Imposta OAUTH_USE_SECONDARY_ROLES = NONE, specifica ALLOWED_ROLES_LIST e utilizza l'ambito Notion session:role:<mcp_access_role>.

Ruoli secondari predefiniti degli utenti (opzionale). Usa questo modello solo se il server ha bisogno dei privilegi ereditati dai DEFAULT_SECONDARY_ROLES di ciascun utente Snowflake. Imposta OAUTH_USE_SECONDARY_ROLES = IMPLICIT, ometti ALLOWED_ROLES_LIST e usa un ambito esplicito per il ruolo principale. Snowflake non consente di usare ruoli secondari IMPLICIT insieme a ALLOWED_ROLES_LIST, quindi ometti la lista di autorizzazione se scegli questo modello.

Utilizza un ruolo dedicato con privilegi minimi per il server MCP ogni volta che è possibile.

Concedi questo ruolo tramite il tuo normale processo di gestione delle identità. Se Okta o SCIM gestiscono l'appartenenza ai ruoli di Snowflake, non aggiungere utenti manualmente al di fuori di tale processo.

Crea o scegli un database e uno schema di cui sia responsabile il team che gestirà il server.

Per rispondere a domande sui dati aziendali soggette a regole di governance, puoi mettere a disposizione dei membri un Cortex Agent come strumento. Riunisce viste semantiche, query verificate, Search e orchestrazione in un unico posto. Un Cortex Agent è opzionale. Se ne crei uno, usa le specifiche riportate di seguito. Se sostituisci un agente esistente, assicurati che quello nuovo rispetti le specifiche approvate.

Altri tipi di strumenti MCP Snowflake supportati includono CORTEX_ANALYST_MESSAGE, CORTEX_SEARCH_SERVICE_QUERY, GENERIC e SYSTEM_EXECUTE_SQL.

Assegna a ogni strumento un nome e una descrizione chiari. Spiega quali dati copre, quanto sono dettagliati i suoi risultati e quando utilizzarlo. Questo aiuta l'agente a scegliere lo strumento giusto.

Il privilegio USAGE su un server MCP consente a un ruolo di connettersi al server e di scoprirne gli strumenti. Non conferisce al ruolo l'accesso al warehouse, all'agente, alla vista semantica, al servizio Search, alla stored procedure o ai dati sottostanti. Concedi al ruolo l'accesso a ciascuna risorsa necessaria agli strumenti del server.

Concedi l'accesso solo alle risorse aggiuntive necessarie a ciascuno strumento. Ad esempio, concedi SELECT su una vista semantica approvata, USAGE su un servizio Cortex Search o USAGE su una funzione o procedura specifica. Non assegnare il ruolo a PUBLIC né aggiungere privilegi estesi per oggetti correnti o futuri.

Prima di configurare OAuth, controlla il server MCP e le relative autorizzazioni:

Configura lo schema MCP in modo che indichi il ruolo esatto che i membri devono richiedere:

Usa un ambito di ruolo esplicito. Non usare session:role:all. Snowflake interpreta questo valore come il ruolo principale predefinito dell'utente, non come accesso a tutti i ruoli. Le policy per i ruoli privilegiati potrebbero bloccarlo. Un ruolo esplicito chiarisce l'accesso richiesto e ne facilita la verifica.

Prima di eseguire questo SQL, coordinati con chi amministra lo spazio di lavoro Notion. Chiedi di inserire l'URL del server Snowflake nel modulo di configurazione MCP dello spazio di lavoro e di attivare Configura manualmente l'autenticazione e Usa un client OAuth condiviso dallo spazio di lavoro. Notion genera un URI di reindirizzamento: copialo e invialo a chi amministra Snowflake. Dopo la creazione dell'ID client e del segreto in Snowflake, sarà possibile completare la configurazione della connessione nello spazio di lavoro.

Utilizza l'URI di reindirizzamento esattamente come fornito da Notion. Non aggiungere una barra finale o parametri di query e non modificare l'host.

IS_AGENTIC = TRUE contrassegna le sessioni create tramite questa integrazione come sessioni degli agenti. La funzione IS_AGENT_ACTIVATED() di Snowflake restituisce quindi TRUE, consentendo a Snowflake di applicare verifiche e regole di governance specifiche per gli agenti. Se usi il modello opzionale con ruoli secondari, imposta OAUTH_USE_SECONDARY_ROLES = IMPLICIT e ometti ALLOWED_ROLES_LIST.

Il valore 7776000 per la validità del token di aggiornamento corrisponde a 90 giorni. Prima di usarlo, verifica che rispetti le regole della tua organizzazione per la riautorizzazione e la rotazione dei token. Per le modifiche ordinarie, evita CREATE OR REPLACE SECURITY INTEGRATION: sostituire l'integrazione può interrompere le connessioni esistenti.

Per verificare l'integrazione senza visualizzarne il segreto, esegui:

Verifica che l'integrazione sia attiva, che l'URI di reindirizzamento corrisponda esattamente, che il ruolo sia consentito e non bloccato, che i token di aggiornamento e PKCE siano attivi e che gli endpoint di autorizzazione e dei token usino l'host pubblico dell'account Snowflake.

Questo passaggio serve solo se la tua organizzazione richiede una policy di rete. Chiedi a chi è responsabile della sicurezza o della rete di approvare gli attuali intervalli di indirizzi IP in uscita di Notion.

L'integrazione OAuth deve consentire entrambi i percorsi di Notion:

1. il percorso API che gestisce i callback OAuth e scambia i codici di autorizzazione

2. il percorso di esecuzione dello spazio di lavoro che convalida la connessione, esegue gli strumenti e aggiorna i token

Questi percorsi potrebbero usare indirizzi IP in uscita di Notion diversi. Se consenti solo l'indirizzo usato per lo scambio iniziale del token, l'accesso potrebbe riuscire, ma la convalida o l'aggiornamento del token potrebbero non funzionare. Usa gli attuali intervalli di indirizzi IP in uscita approvati di Notion. Non aggiungere alla lista di autorizzazione dell'ambiente di produzione un indirizzo IP rilevato una sola volta nel browser o in un registro.

Associa questa policy di rete all'integrazione OAuth, non alle singole persone. Non modificare le policy applicate all'intero account per l'accesso tramite browser o VPN, né quelle per l'accesso alla rete da parte degli utenti. Se una policy di rete blocca una richiesta di token, Snowflake potrebbe restituire invalid_client. Questo errore non significa necessariamente che l'ID client o il segreto siano errati.

Esegui il comando in un foglio di lavoro Snowflake sicuro. Il nome dell'integrazione distingue tra maiuscole e minuscole e di solito è tutto in maiuscolo:

Condividi l'ID client e il relativo segreto con l'amministratore dello spazio di lavoro Notion utilizzando un canale sicuro approvato. Snowflake fornisce due segreti validi, così puoi ruotarli senza tempi di inattività. Non incollare mai nessuno dei due segreti nella documentazione, nelle chat, nei ticket o nei sistemi di controllo delle versioni del codice sorgente.

Quando Snowflake è pronto, chi ha il ruolo di proprietario o di amministratore aggiunge il server allo spazio di lavoro. I membri possono poi trovarlo senza vedere il segreto del client OAuth, sia che colleghino il server MCP di Snowflake a un agente personalizzato sia che lo colleghino al proprio agente di Notion.

1. Apri le Impostazioni dello spazio di lavoro.

2. Seleziona Connessioni → MCP condivisi dello spazio di lavoro.

3. Seleziona Nuovo MCP dello spazio di lavoro.

Compila questi campi, quindi seleziona Aggiungi server MCP:

Dopo aver salvato, conferma che la nuova riga appaia sotto Condiviso con questo spazio di lavoro e che Client OAuth dello spazio di lavoro mostri Configurato.

Cosa fa questa configurazione:

• Aiuta i membri a trovare il server approvato.

• Salva il segreto del client OAuth una sola volta nell'archivio crittografato delle connessioni di Notion.

• Assicura che i membri accedano con l'URL del server, il client e gli ambiti approvati.

• Non crea una sessione Snowflake condivisa né aggira i controlli di accesso di Snowflake.

• Non collega automaticamente tutti i membri. Ogni persona deve accedere separatamente.

Se rimuovi questa configurazione, i nuovi membri non potranno più trovare il server. Le connessioni esistenti potrebbero ancora apparire, quindi coordina questa modifica con la revoca delle autorizzazioni Snowflake e la rimozione delle connessioni esistenti.

Quando la connessione MCP a Snowflake è pronta, puoi usarla in due modi. Se la configuri per un team, inizia dal passaggio 11A. Se vuoi solo fare le tue domande, vai al passaggio 11B. Puoi fare entrambe le cose: sono connessioni separate.

Un agente personalizzato offre al tuo team un unico posto in cui porre domande sui dati di Snowflake. Colleghi Snowflake una volta, aggiungi istruzioni sulle tue metriche e tabelle e condividi l'agente con il tuo team. A chiunque lo utilizzi verrà richiesto di accedere a Snowflake con le proprie credenziali, in modo che ogni persona ottenga risposte basate solo sui dati che è autorizzata a vedere.

Collega Snowflake a un agente personalizzato

1. Apri il tuo agente personalizzato o creane uno nuovo.

2. Vai su Impostazioni → Strumenti e accesso.

3. Seleziona Aggiungi connessione, quindi scegli il server Snowflake etichettato come Gestito dallo spazio di lavoro. Non selezionare Server MCP personalizzato né inserire l'URL del server manualmente.

4. Accedi a Snowflake nel tuo browser. Potrebbe apparire il consueto accesso Okta o SSO della tua organizzazione.

5. Controlla e approva il ruolo Snowflake richiesto.

6. Scegli quali strumenti può utilizzare l'agente. Lascia gli strumenti in grado di scrivere e CORTEX_AGENT_RUN impostati in modo da richiedere l'approvazione finché non li avrai testati.

7. Seleziona Collega e verifica che lo stato della connessione sia Connesso.

Fornisci contesto all'agente

La connessione fornisce all'agente l'accesso a Snowflake. Le tue istruzioni gli indicano come la tua azienda utilizza tali dati. Nelle istruzioni dell'agente, descrivi quali strumenti utilizzare per quali tipi di domande, come il tuo team definisce le metriche chiave e da quali tabelle o viste semantiche iniziare. Alcuni esempi di domande verificate sono molto utili. Per un punto di partenza già pronto, consulta la guida al toolkit Data Scout.

Condividi l'agente

Condividi l'agente con il tuo team nello stesso modo in cui condividi qualsiasi agente personalizzato. La prima volta che qualcuno gli pone una domanda che richiede Snowflake, gli verrà chiesto di accedere con il proprio account Snowflake. Non gli verranno richiesti un ID client o un segreto.

Se vuoi fare domande nella tua chat, collega Snowflake al tuo agente di Notion. Accedi con il tuo account Snowflake: l'agente potrà consultare solo i dati a cui hai accesso.

1. Vai su Impostazioni → Notion AI.

2. Sotto Server MCP, seleziona Aggiungi server MCP.

3. Seleziona il server Snowflake con l'etichetta Gestito dallo spazio di lavoro. Non selezionare Server MCP personalizzato né inserire manualmente l'URL del server.

4. Seleziona Collega.

5. Accedi a Snowflake nel tuo browser. Potrebbe apparire il consueto accesso Okta o SSO della tua organizzazione.

6. Controlla e approva il ruolo Snowflake richiesto.

7. Quando il browser ti chiede se aprire Notion, seleziona Apri Notion.

8. Conferma che lo stato del server sia Connesso, non Richiede autenticazione.

Una volta stabilita la connessione, Snowflake compare nella chat in Tutte le fonti → Server MCP.

1. Poni una domanda innocua di cui conosci la risposta e che dovrebbe richiedere l'uso di Snowflake.

2. Conferma che l'agente utilizzi Snowflake e restituisca un risultato.

3. Conferma di non poter accedere ai dati al di fuori del ruolo che ti è stato assegnato.

Se configuri un agente personalizzato, chiedi anche a un membro del team con un ruolo Snowflake più limitato di provarlo. Dovrebbe vedere solo i propri dati, non i tuoi. Questo è il modo più rapido per confermare che l'agente stia utilizzando l'accesso di ogni persona anziché quello del creatore.

Per un controllo più approfondito, chiedi al tuo amministratore Snowflake di confermare il tuo utente, ruolo, warehouse e cronologia delle query. Un accesso riuscito conferma la tua identità, ma non conferma che ogni autorizzazione sia corretta.

Poni all'agente una domanda specifica sui tuoi dati Snowflake. Ad esempio:

• «Secondo i dati di Snowflake, quante iscrizioni abbiamo registrato in totale il mese scorso?»

• «Secondo i dati di Snowflake, quali sono stati i nostri 10 account con i ricavi più alti questo trimestre?»

Con un agente personalizzato, di solito puoi omettere «da Snowflake» se le istruzioni indicano chiaramente quando usarlo. Con l'agente di Notion, specificare Snowflake aiuta a scegliere la fonte giusta.

Le richieste più complesse possono richiedere più tempo o scadere prima di essere completate. In tal caso, fai una domanda più specifica oppure dividi la richiesta in domande più piccole.

Di solito non devi fare nulla per mantenere la connessione. Snowflake usa token di accesso di breve durata, che Notion aggiorna in background. La scadenza imminente di un token di accesso, da sola, non interrompe la connessione.

Dovrai accedere di nuovo se:

• Il tuo token di aggiornamento scade o un amministratore lo revoca

• Un amministratore sostituisce l'integrazione OAuth o il segreto client

• Il tuo ruolo Snowflake viene rimosso

• Un amministratore rimuove la configurazione dello spazio di lavoro o la tua connessione

• Una policy di rete blocca l'aggiornamento del token

Con un agente personalizzato, l'accesso di ogni persona è separato. Se a una persona viene chiesto di accedere di nuovo, ciò non influisce su nessun altro e la persona che ha creato l'agente non deve fare nulla.

Se devi eseguire la rotazione del segreto client: usa la rotazione con due segreti di Snowflake invece di sostituire l'integrazione. Mantieni validi entrambi i segreti per il tempo necessario ad aggiornare e verificare la configurazione dello spazio di lavoro, prima di disattivare quello precedente.

ALTER SECURITY INTEGRATION <oauth_integration_name>
REFRESH OAUTH_CLIENT_SECRET_2;

• La connessione Snowflake MCP non è elencata. L'amministratore del tuo spazio di lavoro potrebbe non averla ancora aggiunta, oppure il tuo spazio di lavoro potrebbe limitare i server personalizzati. Chiedi aiuto al tuo amministratore.

• Ti viene chiesto un ID client o un segreto. Probabilmente hai scelto l'opzione per il server MCP personalizzato. Torna indietro e scegli il server Snowflake con l'etichetta Gestito dallo spazio di lavoro.

• Ti viene chiesto di accedere di nuovo. La tua sessione Snowflake potrebbe essere scaduta o un amministratore potrebbe aver aggiornato la connessione. Accedi di nuovo a Snowflake.

• Hai aperto un agente personalizzato e ti è stato chiesto di accedere a Snowflake. È normale la prima volta. Ogni persona che utilizza un agente personalizzato gestito deve accedere con le proprie credenziali Snowflake.

• Un membro del team ottiene risultati diversi dallo stesso agente personalizzato. È normale. L'agente utilizza l'accesso Snowflake di ogni persona, quindi persone con ruoli diversi vedono dati diversi.

• L'agente personalizzato funziona in chat, ma non nelle esecuzioni programmate. Le esecuzioni programmate e quelle attivate da un trigger non sono associate a una persona che ha effettuato l'accesso, quindi non possono ancora usare Snowflake con l'accesso individuale.

• Hai effettuato l'accesso, ma la connessione non riesce o gli strumenti non funzionano. L'accesso verifica la tua identità, ma le operazioni che puoi compiere dipendono comunque dai privilegi che ti sono stati concessi in Snowflake. Chiedi al tuo amministratore Snowflake di verificare che il tuo ruolo abbia accesso al server, al warehouse, all'agente e ai dati.

• L'agente non riesce a trovare una tabella. L'agente può accedere solo ai dati accessibili dal tuo account Snowflake. Controlla i tuoi permessi in Snowflake e indica il nome della tabella nella domanda.

• Una richiesta scade prima di essere completata. Fai una domanda più specifica oppure suddividi la richiesta in domande più brevi.

Questi errori solitamente derivano dalle impostazioni di Snowflake, non da Notion. Condividili con il tuo amministratore Snowflake.

• L'URL del server sembra raddoppiato, come https://https%3A... L'indirizzo è stato incollato con un https:// aggiuntivo davanti. Correggilo in modo che l'URL inizi con un solo https://.

• Vedi "This server does not support OAuth authentication." L'integrazione di sicurezza non è configurata per OAuth o l'URL del server è errato. Chiedi al tuo amministratore Snowflake di controllare l'integrazione di sicurezza OAuth e l'URL del server.

• Vedi invalid_client durante l'accesso o l'aggiornamento. L'ID client o il segreto è errato, oppure il segreto è stato modificato. Chiedi al tuo amministratore l'ID client e il segreto correnti.

• L'accesso riesce, ma subito dopo si verifica un errore. Il tuo ruolo potrebbe non avere accesso al server, oppure un ruolo o una regola di rete potrebbe bloccare la sessione. Chiedi al tuo amministratore di verificare i tuoi permessi e le regole applicate.

• Vedi "The role ALL requested has been explicitly blocked." La connessione ha richiesto tutti i ruoli contemporaneamente (session:role:all), e questa richiesta è bloccata. Usa invece un solo ruolo con il nome esatto, come session:role:analyst, sostituendo analyst con il nome del tuo ruolo.

• Vedi un errore di reindirizzamento (errore 390307). L'URL di reindirizzamento salvato in Snowflake non corrisponde a quello usato da Notion. Chiedi al tuo amministratore di impostare nell'integrazione di sicurezza l'esatto URL di reindirizzamento usato da Notion.

• Vedi l'errore 390311 relativo a una code challenge non valida. Si tratta di una mancata corrispondenza PKCE. Chiedi al tuo amministratore di confermare che OAUTH_ENFORCE_PKCE sia impostato correttamente sull'integrazione di sicurezza.

• Sei connesso, ma non viene visualizzato alcuno strumento. Al tuo ruolo potrebbe mancare USAGE sul server MCP. Chiedi al tuo amministratore di confermare l'autorizzazione, quindi esegui DESCRIBE MCP SERVER per verificare la configurazione.

• Puoi accedere a più o meno dati di quanto previsto. I ruoli secondari modificano ciò che la tua sessione può vedere. Verifica con il tuo amministratore quali ruoli sono attivi nella tua sessione.

• Prima funzionava, ma dopo la modifica del segreto non funziona più per nessuno. Il segreto del client è stato sostituito, quindi la connessione salvata non è aggiornata. Chiedi al tuo amministratore il nuovo segreto, poi connettiti di nuovo.

• Prima funzionava, ma ora non funziona più solo per te. Un ruolo, un'autorizzazione o una policy potrebbero essere cambiati, oppure la tua sessione è scaduta. Accedi di nuovo, quindi chiedi al tuo amministratore di confermare che il tuo accesso non sia cambiato.

• Il tuo identificativo dell'account viene rifiutato. Usa il formato organization-account, con un trattino anziché punti, per esempio myorg-myaccount.

• Un account PrivateLink non riesce a connettersi. Gli account PrivateLink richiedono una configurazione di rete aggiuntiva. Chiedi al tuo amministratore se PrivateLink consente la connessione da Notion.

• Snowflake non è disponibile nelle esecuzioni programmate o attivate da un trigger. Queste esecuzioni non sono associate a una persona che ha effettuato l'accesso, quindi non possono ancora usare l'accesso individuale. Esegui la richiesta in chat.

• Vedi oauth_security_error dopo aver effettuato l'accesso dal browser. Una regola di rete a livello di account potrebbe bloccare la richiesta. Il tuo amministratore può verificarlo eseguendo:

• L'accesso sembra funzionare ma ricevi un errore di ruolo, anche con l'ambito corretto. Il tuo ruolo predefinito potrebbe essere bloccato, ad esempio ACCOUNTADMIN o un ruolo in BLOCKED_ROLES_LIST. Il tuo amministratore può verificare e risolvere il problema:

Questi comandi di sola lettura aiutano il tuo amministratore a confermare la configurazione senza modificare nulla. Eseguili in Snowflake.

Utilizza queste guide di Snowflake per completare la configurazione:

• Server MCP gestito da Snowflake

• Creare un'integrazione di sicurezza OAuth di Snowflake

• OAuth di Snowflake per client personalizzati

• Panoramica di Snowflake OAuth

• Identificatori dell'account Snowflake

• Agenti personalizzati

• Connessioni MCP per agenti personalizzati

• Collega i server MCP al tuo agente di Notion

• Buone pratiche di sicurezza per le connessioni degli agenti