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 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 collegare gli agenti personalizzati all'MCP di Snowflake usando le proprie credenziali Snowflake, oppure collegare Snowflake direttamente al proprio agente di Notion. I passaggi da 1 a 10 di questo articolo sono uguali per entrambi i percorsi. Dal passaggio 11, le istruzioni cambiano in base all'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 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. 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, quando 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 per ciascun account (opzionali). Usa questo modello solo se il server ha bisogno dei privilegi ereditati dai DEFAULT_SECONDARY_ROLES di ciascun account Snowflake. Imposta OAUTH_USE_SECONDARY_ROLES = IMPLICIT, ometti ALLOWED_ROLES_LIST e usa un ambito esplicito per il ruolo principale. Snowflake non consente ruoli secondari IMPLICIT insieme a ALLOWED_ROLES_LIST, quindi ometti la lista di autorizzazione se usi questo modello.

Utilizza un ruolo dedicato con privilegi minimi per il server MCP, quando 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 proprietà del team che gestirà il server.

Per le domande aziendali soggette a governance, puoi esporre un Cortex Agent come strumento utilizzato dai membri. Riunisce viste semantiche, query verificate, Search e orchestrazione in un unico posto. Un Cortex Agent è opzionale. Se ne crei uno, utilizza la specifica seguente. Se sostituisci un agente esistente, assicurati che quello nuovo sia conforme alla 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 i privilegi che gli sono stati concessi:

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

Utilizza un ambito di ruolo esplicito. Non utilizzare session:role:all. Snowflake considera quel valore come il ruolo principale predefinito dell'utente, non come accesso a tutti i ruoli, e i criteri per i ruoli privilegiati potrebbero bloccarlo. Un ruolo esplicito rende più chiaro e più facile da verificare l'accesso richiesto.

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 la creazione dell'ID client e del segreto in Snowflake, chi amministra lo spazio di lavoro potrà completare la configurazione della connessione.

Usa 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, consentendo a Snowflake di applicare controlli e regole di governance specifici per gli agenti. Se utilizzi il modello opzionale dei ruoli secondari, imposta OAUTH_USE_SECONDARY_ROLES = IMPLICIT e ometti ALLOWED_ROLES_LIST.

Il valore di validità del token di aggiornamento, 7.776.000 secondi, equivale a 90 giorni. Prima di usarlo, verifica che sia conforme alle regole della tua organizzazione sulla riautorizzazione e sulla 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 si occupa della sicurezza o della rete di approvare gli intervalli attuali degli 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 runtime 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 autorizzi solo l'indirizzo usato per lo scambio iniziale del token, l'accesso potrebbe riuscire, ma la convalida della connessione o l'aggiornamento del token potrebbero non funzionare. Usa gli intervalli attuali e approvati degli indirizzi IP in uscita 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 ai singoli utenti. Non modificare le policy dell'intero account relative all'accesso tramite browser, alla VPN o all'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.

Eseguilo in un foglio di lavoro Snowflake sicuro. Il nome dell'integrazione è sensibile alle maiuscole e solitamente è in maiuscolo:

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

Quando Snowflake è pronto, chi è proprietario o amministra lo spazio di lavoro aggiunge il server una sola volta. I membri possono quindi trovarlo senza vedere il segreto del client OAuth, sia per collegare il server MCP di Snowflake a un agente personalizzato sia per collegarlo 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 il salvataggio, verifica 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.

• Memorizza una sola volta il segreto del client OAuth 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 connette automaticamente ogni membro. 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 di Snowflake e la rimozione delle connessioni esistenti.

Quando la connessione MCP di Snowflake è pronta, puoi usarla in due modi. Se la stai configurando per un team, inizia dal punto 11A. Se vuoi solo fare le tue domande, vai al punto 11B. Puoi anche seguire entrambi i percorsi: le connessioni sono 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 ha il permesso di 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. Verifica e approva il ruolo Snowflake richiesto.

6. Scegli quali strumenti può usare l'agente. Finché non li avrai testati, lascia impostati per richiedere l'approvazione gli strumenti che possono scrivere dati e CORTEX_AGENT_RUN.

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

Fornisci contesto all'agente

La connessione dà all'agente accesso a Snowflake. Le tue istruzioni gli spiegano come la tua azienda usa quei dati. Nelle istruzioni dell'agente, indica quali strumenti usare per ciascun tipo di domanda, come il tuo team definisce le metriche principali e da quali tabelle o viste semantiche partire. Bastano poche domande di esempio verificate per aiutarlo a rispondere. Per iniziare, 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 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. Verifica 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. Fai una domanda semplice di cui conosci la risposta e per cui servono i dati di Snowflake.

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

3. Verifica di non poter accedere ai dati non consentiti dal 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 all'amministratore di 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 avuto 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 spiegano quando usare questa fonte. Con il tuo agente di Notion, citare Snowflake lo aiuta a scegliere la fonte giusta.

Le richieste complesse possono richiedere più tempo o scadere. Se succede, fai una domanda più specifica o suddividi la richiesta in domande più semplici.

Di solito la connessione resta attiva senza che tu debba fare nulla. Snowflake usa token di accesso a breve durata, che Notion 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, 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 stai sostituendo il segreto client: Usa la procedura di rotazione dei 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. Solo allora disattiva quello vecchio.

ALTER SECURITY INTEGRATION <oauth_integration_name>
REFRESH OAUTH_CLIENT_SECRET_2;

• La connessione MCP a Snowflake non compare nell'elenco. L'amministratore dello spazio di lavoro potrebbe non averla ancora aggiunta oppure lo spazio di lavoro potrebbe limitare l'uso di server personalizzati. Chiedi aiuto all'amministratore.

• Ti viene chiesto un ID client o un segreto. Probabilmente hai scelto l'opzione MCP personalizzata. Torna indietro e scegli invece 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 utilizza l'accesso Snowflake di ogni persona, quindi le persone con ruoli diversi vedono dati diversi.

• L'agente personalizzato funziona in chat, ma non nelle esecuzioni pianificate. 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 la connessione non riesce o gli strumenti non funzionano. L'autenticazione conferma la tua identità, ma l'accesso dipende comunque dalle autorizzazioni che hai 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 a cui ha accesso il tuo account Snowflake. Controlla le tue autorizzazioni in Snowflake e includi il nome della tabella nella domanda.

• La 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 le tue autorizzazioni e policy.

• 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 solo 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 l'URL di reindirizzamento esatto usato da Notion.

• Vedi l'errore 390311 relativo a un code challenge non valido. 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. Il tuo ruolo potrebbe non avere il permesso USAGE per il server MCP. Chiedi al tuo amministratore di verificare l'autorizzazione, poi esegui DESCRIBE MCP SERVER per controllare la configurazione.

• Hai accesso a più o meno dati del previsto. I ruoli secondari determinano quali dati sono accessibili nella tua sessione. Verifica con il tuo amministratore quali ruoli sono attivi.

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

• Prima funzionava, ma ora non funziona più solo per te. Potrebbero essere cambiati un ruolo, un'autorizzazione o una policy, oppure la tua sessione potrebbe essere scaduta. Accedi di nuovo, poi chiedi al tuo amministratore di verificare se le tue autorizzazioni sono cambiate.

• Il tuo identificativo account viene rifiutato. Usa il formato organization-account, con un trattino e senza punti, come 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 a Notion.

• Snowflake non è disponibile nelle esecuzioni pianificate 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 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 permettono al tuo amministratore di verificare 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