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) gestito 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 o amministratore dello spazio di lavoro Notion configura la connessione MCP di Snowflake per lo spazio di lavoro.

• I membri dello spazio di lavoro possono quindi collegarsi all'MCP di Snowflake dagli agenti personalizzati usando le proprie credenziali Snowflake, oppure collegare Snowflake direttamente al proprio agente di Notion. I passaggi da 1 a 10 sono gli stessi in entrambi i casi. Dal passaggio 11, segui le istruzioni per l'agente che vuoi collegare.

• 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 il permesso di 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. Verifica 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 dell'utente (opzionali). Usa questo modello solo se il server ha bisogno dei privilegi ereditati dai ruoli DEFAULT_SECONDARY_ROLES di ciascun utente Snowflake. Imposta OAUTH_USE_SECONDARY_ROLES = IMPLICIT, ometti ALLOWED_ROLES_LIST e specifica esplicitamente l'ambito del ruolo principale. Snowflake non consente di usare i ruoli secondari IMPLICIT insieme a ALLOWED_ROLES_LIST, quindi con questo modello ometti la lista di autorizzazione.

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

Assegna questo ruolo seguendo il consueto processo di gestione delle identità. Se l'appartenenza ai ruoli Snowflake è gestita tramite Okta o SCIM, non aggiungere utenti manualmente al di fuori di quel processo.

Crea o scegli un database e uno schema di proprietà del team che eseguirà il server.

Per rispondere a domande sui dati aziendali soggetti a regole di governance, puoi rendere disponibile un Cortex Agent come strumento per i membri. Riunisce viste semantiche, query verificate, Search e orchestrazione. Cortex Agent è opzionale. Se ne crei uno, usa la specifica qui sotto. Se sostituisci un agente esistente, verifica che quello nuovo rispetti la specifica approvata.

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. Inoltre, le policy per i ruoli con privilegi elevati potrebbero bloccarlo. Un ruolo esplicito rende l'accesso richiesto più chiaro e facile da verificare.

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 Manually configure authentication e Use a workspace-shared OAuth client. Notion genera un URI di reindirizzamento. Copialo e invialo a chi amministra Snowflake. Dopo che Snowflake avrà creato l'ID client e il segreto, chi amministra lo spazio di lavoro potrà completare la configurazione della connessione.

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

L'impostazione IS_AGENTIC = TRUE contrassegna le sessioni create tramite questa integrazione come sessioni degli agenti. La funzione IS_AGENT_ACTIVATED() di Snowflake restituisce quindi TRUE, il che consente a Snowflake di applicare l'auditing e la governance specifici per gli agenti. Se utilizzi il modello di ruolo secondario opzionale, imposta OAUTH_USE_SECONDARY_ROLES = IMPLICIT e ometti ALLOWED_ROLES_LIST.

Il valore di validità del token di aggiornamento di 7776000 secondi equivale a 90 giorni. Prima di utilizzarlo, conferma che corrisponda alle politiche di riautorizzazione e rotazione dei token della tua organizzazione. Per modifiche di routine, evita CREATE OR REPLACE SECURITY INTEGRATION. La sostituzione dell'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 del 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 durante lo scambio iniziale del token, l'accesso potrebbe riuscire, ma la convalida o l'aggiornamento del token potrebbero non riuscire. 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 da un browser o da un registro.

Applica questa policy di rete all'integrazione OAuth, non ai singoli utenti. Non modificare le policy a livello di account per l'accesso tramite browser, VPN o 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 è scritto tutto in maiuscolo:

Condividi l'ID client e il segreto corrispondente con chi amministra lo spazio di lavoro Notion tramite un canale sicuro approvato. Snowflake fornisce due segreti validi, che puoi alternare senza interrompere il servizio. Non incollare mai nessuno dei due nella documentazione, nelle chat, nei ticket o in un sistema di controllo versione.

Una volta che Snowflake è pronto, un proprietario o un amministratore dello spazio di lavoro aggiunge il server una volta per lo spazio di lavoro. I membri possono quindi trovarlo senza vedere il segreto del client OAuth, sia che stiano collegando l'MCP di Snowflake a un agente personalizzato o al proprio agente di Notion.

1. Apri 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, verifica che la nuova riga compaia 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.

• Memorizza 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 chi amministra lo spazio di lavoro ha preparato la connessione MCP di Snowflake, puoi usarla in due modi. Se la configuri per un team, inizia dal passaggio 11A. Se vuoi solo porre le tue domande, vai al passaggio 11B. Puoi fare entrambe le cose: le connessioni sono separate.

Un agente personalizzato offre al tuo team un unico punto di riferimento per le domande sui dati di Snowflake. Colleghi Snowflake una sola volta, aggiungi istruzioni sulle tue metriche e tabelle e condividi l'agente con il team. Ogni persona che lo usa deve accedere a Snowflake con le proprie credenziali, così riceve risposte basate solo sui dati a cui ha accesso.

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. Esamina e approva il ruolo Snowflake richiesto.

6. Scegli quali strumenti può usare l'agente. Mantieni gli strumenti con permessi di scrittura e CORTEX_AGENT_RUN impostati in modo da richiedere l'approvazione finché non li avrai testati.

7. Seleziona Collega e verifica che la connessione risulti Collegata.

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 come faresti con qualsiasi altro agente personalizzato. La prima volta che qualcuno gli pone una domanda che richiede Snowflake, dovrà accedere con il proprio account Snowflake. Non dovrà inserire un ID client né un segreto.

Se vuoi fare domande direttamente nella tua chat, collega Snowflake al tuo agente di Notion. Accedi con il tuo account Snowflake: l'agente potrà usare 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 etichettato come Gestito dallo spazio di lavoro. Non selezionare Server MCP personalizzato né inserire l'URL del server manualmente.

4. Seleziona Collega.

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

6. Esamina e approva il ruolo Snowflake richiesto.

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

8. Verifica che lo stato del server sia Connesso e non Richiede autenticazione.

Dopo aver stabilito la connessione, Snowflake compare nella chat in Tutte le fonti → Server MCP.

1. Poni una domanda non rischiosa di cui conosci la risposta e che richieda l'uso di Snowflake.

2. Verifica che l'agente usi Snowflake e restituisca un risultato.

3. Verifica di non poter accedere ai dati per cui il tuo ruolo non dispone delle autorizzazioni necessarie.

Se hai configurato un agente personalizzato, chiedi anche a un membro del team con un ruolo Snowflake più limitato di provarlo. Dovrebbe vedere solo i dati a cui ha accesso, non tutti quelli che puoi vedere tu. È il modo più rapido per verificare che l'agente usi l'accesso di ogni persona e non quello di chi lo ha creato.

Per un controllo più approfondito, chiedi a chi amministra Snowflake di verificare il tuo account utente, il ruolo, il warehouse e la cronologia delle query. L'accesso riuscito conferma la tua identità, ma non che tutte le autorizzazioni siano corrette.

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 “secondo i dati di Snowflake” se le istruzioni indicano già quando usarlo. Con il tuo agente di Notion, citare Snowflake lo aiuta a scegliere la fonte giusta.

Le richieste molto ampie possono richiedere più tempo o scadere prima di essere completate. In quel caso, poni una domanda più specifica o suddividi la richiesta in domande più piccole.

Nella maggior parte dei casi, la connessione resta attiva senza che tu debba fare nulla. Snowflake usa token di accesso di breve durata e Notion li aggiorna in background. La scadenza 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, ogni persona accede separatamente. Se qualcuno deve accedere di nuovo, le altre persone non ne risentono e chi ha creato l'agente non deve fare nulla.

Se devi aggiornare il segreto client: Usa la procedura di rotazione con due segreti di Snowflake, invece di sostituire l'integrazione. Mantieni validi entrambi i segreti finché non avrai aggiornato e testato la configurazione dello spazio di lavoro, poi disattiva quello precedente.

ALTER SECURITY INTEGRATION <oauth_integration_name>
REFRESH OAUTH_CLIENT_SECRET_2;

• La connessione MCP di Snowflake non compare nell'elenco. Chi amministra lo spazio di lavoro potrebbe non averla ancora aggiunta, oppure lo spazio di lavoro potrebbe limitare l'uso di server personalizzati. Chiedi assistenza a chi amministra lo spazio di lavoro.

• Ti viene chiesto un ID client o un segreto. Probabilmente hai scelto l'opzione per un server MCP personalizzato. Torna indietro e scegli il server Snowflake contrassegnato come 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 usa l'accesso Snowflake di ogni persona, quindi chi ha ruoli diversi vede dati diversi.

• L'agente personalizzato funziona nella chat, ma non può essere eseguito a intervalli programmati. Le esecuzioni pianificate 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 non riesci a connetterti o gli strumenti non funzionano. L'autenticazione conferma la tua identità, ma ciò a cui puoi accedere dipende comunque dalle autorizzazioni che hai in Snowflake. Chiedi al tuo amministratore Snowflake di confermare che il tuo ruolo consenta di accedere al server, al warehouse, all'agente e ai dati.

• L'agente non riesce a trovare una tabella. L'agente può raggiungere solo i dati che il tuo account Snowflake può raggiungere. Controlla le tue autorizzazioni Snowflake e includi il nome della tabella nella tua domanda.

• La richiesta scade. Fai una domanda più specifica oppure suddividi la richiesta in domande più semplici.

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 oppure 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 non sono corretti, oppure il segreto è stato modificato. Chiedi al tuo amministratore l'ID client e il segreto attuali.

• L'accesso riesce, ma poi fallisce subito. Il tuo ruolo potrebbe non consentirti di accedere al server, oppure una regola legata al ruolo o alla rete potrebbe bloccare la sessione. Chiedi al tuo amministratore di verificare le autorizzazioni e le policy applicabili.

• Vedi «The role ALL requested has been explicitly blocked.» La connessione ha richiesto tutti i ruoli contemporaneamente (session:role:all), ma questa richiesta è bloccata. Usa invece un ruolo specifico, 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 esattamente l'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 ti aspettassi. 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 nessuno riesce più a connettersi. 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 sei l'unica persona per cui non funziona. Un ruolo, un'autorizzazione o una policy potrebbero essere cambiati, oppure la tua sessione potrebbe essere scaduta. Accedi di nuovo, poi chiedi al tuo amministratore di verificare che le tue autorizzazioni non siano cambiate.

• Il tuo identificativo account viene rifiutato. Usa il formato organization-account con un trattino, come myorg-myaccount, senza punti.

• 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 a Notion.

• Snowflake non è disponibile nelle esecuzioni pianificate o attivate da un trigger. Tali esecuzioni non hanno una persona che ha effettuato l'accesso, quindi non possono ancora utilizzare l'accesso per utente. Esegui la tua richiesta nella chat.

• Vedi oauth_security_error dopo aver effettuato l'accesso tramite il browser. Una policy di rete a livello di account potrebbe bloccare la richiesta. Il tuo amministratore può confermare 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 verificare la configurazione senza modificare nulla. Chiedigli di eseguirli 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

• Migliori pratiche di sicurezza per le connessioni degli agenti