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.

• Chi fa parte dello spazio di lavoro può connettersi 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 uguali 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.

Prima di iniziare, compila questa tabella insieme a chi amministra il tuo spazio di lavoro Notion. Chi fa parte dello spazio di lavoro può saltare questo passaggio e accedere con il proprio account Snowflake al termine della 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 di un utente (opzionali). Utilizza questo modello solo quando il server necessita di privilegi ereditati dai DEFAULT_SECONDARY_ROLES Snowflake di ogni utente. Imposta OAUTH_USE_SECONDARY_ROLES = IMPLICIT, ometti ALLOWED_ROLES_LIST e utilizza un ambito esplicito per il ruolo principale. Snowflake non consente ruoli secondari IMPLICIT con ALLOWED_ROLES_LIST, quindi ometti la lista di autorizzazione quando utilizzi 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 proprietà del team che eseguirà il server.

Per rispondere a domande aziendali su dati soggetti a controlli, puoi rendere disponibile un Cortex Agent come strumento per chi fa parte dello spazio di lavoro. Riunisce viste semantiche, query verificate, ricerca e orchestrazione in un unico punto. Un Cortex Agent è opzionale. Se ne crei uno, usa le specifiche seguenti. Se sostituisci un agente esistente, verifica che quello nuovo sia conforme alle 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 individuare gli strumenti disponibili. Non dà accesso al warehouse, all'agente, alla vista semantica, al servizio di ricerca, 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 per indicare 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 regole per i ruoli privilegiati potrebbero bloccarlo. Un ruolo esplicito chiarisce quale accesso viene richiesto e facilita le verifiche.

Prima di eseguire questo SQL, coordinati con l'amministratore dello spazio di lavoro Notion. Chiedigli 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 all'amministratore di Snowflake. Dopo che Snowflake avrà creato l'ID client e il segreto, l'amministratore dello 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 dell'agente. La funzione IS_AGENT_ACTIVATED() di Snowflake restituisce quindi TRUE, consentendo a Snowflake di applicare controlli di audit e governance specifici 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 è espresso in secondi e corrisponde a 90 giorni. Prima di usarlo, verifica che sia conforme alle regole della tua organizzazione sulla nuova autorizzazione 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 e che i token di aggiornamento e PKCE siano attivi. Controlla anche 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 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 consenti 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 di indirizzi IP in uscita attuali e approvati di Notion. Non aggiungere alla lista di autorizzazione dell'ambiente di produzione un indirizzo IP trovato una sola volta in un browser o in un registro.

Allega questa policy di rete all'integrazione OAuth, non ai singoli utenti. Non modificare le policy a livello di account per l'accesso tramite browser, l'accesso VPN o l'accesso degli utenti alla rete. 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 relativo segreto con l'amministratore dello spazio di lavoro Notion tramite un canale sicuro approvato. Snowflake fornisce due segreti validi, così puoi ruotarli senza interruzioni del servizio. Non incollare mai nessuno dei due segreti nella documentazione, nelle chat, nei ticket o nei sistemi di controllo delle versioni del codice.

Quando Snowflake è pronto, chi è proprietario o amministratore dello spazio di lavoro aggiunge il server per tutto lo spazio di lavoro. Gli altri membri possono quindi trovarlo senza vedere il segreto del client OAuth, sia per collegare l'MCP di Snowflake a un agente personalizzato sia per collegarlo al proprio agente di Notion.

1. Vai su Impostazioni per lo 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 comporta questa configurazione:

• Aiuta i membri a trovare il server approvato.

• Conserva il segreto del client OAuth in un unico punto, nell'archivio cifrato 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 essere visibili: coordina quindi la rimozione con la revoca delle autorizzazioni Snowflake e l'eliminazione 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 domande per conto tuo, passa al passaggio 11B. Puoi anche seguire entrambi i percorsi: le connessioni sono separate.

Un agente personalizzato offre al tuo team un unico punto in cui fare domande sui dati di Snowflake. Colleghi Snowflake una sola volta, aggiungi istruzioni sulle metriche e sulle tabelle e condividi l'agente con il tuo team. Ogni persona che lo usa deve accedere a Snowflake con le proprie credenziali, così riceve risposte basate solo sui dati che può 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ò usare l'agente. Mantieni la richiesta di approvazione per gli strumenti che possono scrivere dati e per CORTEX_AGENT_RUN finché non li hai 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, così l'agente potrà consultare solo i dati a cui hai accesso.

1. Vai su Impostazioni → Notion AI.

2. Nella sezione 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. 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 con una risposta nota che dovrebbe utilizzare Snowflake.

2. Verifica che l'agente usi 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 a chi amministra Snowflake di verificare il tuo utente, il ruolo, il warehouse e la cronologia delle query. Un accesso riuscito conferma la tua identità, ma non garantisce che tutte le autorizzazioni siano corrette.

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

• “In Snowflake, quante iscrizioni abbiamo registrato il mese scorso?”

• “In Snowflake, quali sono i 10 account che hanno generato più ricavi in questo trimestre?”

Con un agente personalizzato, di solito puoi omettere “in Snowflake” quando le istruzioni indicano chiaramente quando usare questa fonte. Con il tuo agente di Notion, specificare Snowflake lo aiuta a scegliere la fonte giusta.

Le richieste complesse possono richiedere più tempo o superare il tempo limite. Se succede, poni una domanda più circoscritta o suddividi la richiesta in più domande.

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 sola scadenza di un token di accesso non interrompe la connessione.

Dovrai accedere di nuovo se:

• Il tuo token di aggiornamento scade o chi amministra il sistema lo revoca

• Chi amministra il sistema sostituisce l'integrazione OAuth o il segreto client

• Il tuo ruolo Snowflake viene rimosso

• Chi amministra lo spazio di lavoro ne rimuove la configurazione o elimina la tua connessione

• Una regola 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 rotazione a due segreti di Snowflake, anziché sostituire l'integrazione. Mantieni validi entrambi i segreti per il tempo necessario ad aggiornare e testare la configurazione dello spazio di lavoro prima di disattivare quello precedente.

ALTER SECURITY INTEGRATION <oauth_integration_name>
REFRESH OAUTH_CLIENT_SECRET_2;

• La connessione MCP a 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 i server MCP personalizzati. Torna indietro e seleziona il server Snowflake contrassegnato come Gestito dallo spazio di lavoro.

• Ti viene chiesto di accedere di nuovo. La tua sessione Snowflake potrebbe essere scaduta oppure chi amministra la connessione potrebbe averla aggiornata. 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 a Snowflake di ciascuna persona, quindi chi ha ruoli diversi vede dati diversi.

• L'agente personalizzato funziona nella 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 si stabilisce o gli strumenti non funzionano. L'accesso conferma la tua identità, ma le risorse a cui puoi accedere dipendono comunque dalle tue autorizzazioni 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 le tue autorizzazioni Snowflake e includi il nome della tabella nella domanda.

• Una richiesta supera il tempo limite. Fai una domanda più specifica oppure dividi 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://.

• Visualizzi il messaggio «This server does not support OAuth authentication.» L'integrazione di sicurezza non è configurata per OAuth oppure l'URL del server è errato. Chiedi all'amministratore di Snowflake di verificare l'integrazione di sicurezza OAuth e l'URL del server.

• Visualizzi invalid_client durante l'accesso o l'aggiornamento. L'ID client o il segreto potrebbero essere errati, oppure il segreto potrebbe essere stato modificato. Chiedi all'amministratore l'ID client e il segreto attuali.

• L'accesso riesce, ma subito dopo si verifica un errore. Il tuo ruolo potrebbe non consentirti di accedere al server oppure un ruolo o una regola di rete potrebbe bloccare la sessione. Chiedi all'amministratore di verificare le tue autorizzazioni e le policy.

• Visualizzi il messaggio «The role ALL requested has been explicitly blocked.» La connessione ha richiesto tutti i ruoli contemporaneamente (session:role:all), ma questa richiesta è bloccata. Indica invece un solo ruolo con il suo nome esatto, ad esempio session:role:analyst se il tuo ruolo si chiama analyst.

• Vedi un errore di reindirizzamento (errore 390307). L'URL di reindirizzamento salvato in Snowflake non corrisponde a quello utilizzato da Notion. Chiedi al tuo amministratore di impostare nell'integrazione di sicurezza l'URL di reindirizzamento esattamente come previsto 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 non funziona più per nessuno. Il segreto del client è stato sostituito, quindi la connessione salvata non è aggiornata. Chiedi all'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 account viene rifiutato. Utilizza il formato organization-account con un trattino, come myorg-myaccount, non i 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 programmate o attivate da un trigger. Nessuno ha effettuato l'accesso per queste esecuzioni, quindi non possono ancora usare l'accesso individuale. Esegui la 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ò 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

• Crea 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