Configura l'MCP di Snowflake per Notion

I tuoi agenti personalizzati e il tuo agente di Notion possono collegarsi 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 collegarsi all'MCP di Snowflake dagli agenti personalizzati utilizzando le proprie credenziali Snowflake, oppure collegare 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 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 essere sul piano Business o sul piano 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 utilizza trattini, non trattini bassi. Assicurati che ogni nome oggetto nell'URL del server corrisponda al nome oggetto corrispondente 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 di un utente (opzionale). 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 di ruolo primario esplicito. 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 i privilegi minimi necessari per il server MCP, quando possibile.

Concedi questo ruolo tramite il tuo normale processo di gestione delle identità. Se Okta o SCIM gestisce 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 le domande aziendali regolate, puoi esporre un Cortex Agent come strumento utilizzato dai membri. Mantiene viste semantiche, query verificate, Cerca 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 la sostituzione corrisponda 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 collegarsi al server e di scoprirne gli strumenti. Non conferisce al ruolo l'accesso al warehouse, all'agente, alla visualizzazione semantica, al servizio di Cerca, 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 sue autorizzazioni:

Configura lo schema MCP per indicare il ruolo esatto che i membri devono richiedere:

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

Prima di eseguire questo SQL, coordinati con l'amministratore dello spazio di lavoro Notion. Richiedi che inserisca l'URL del server Snowflake nel modulo di configurazione MCP dello spazio di lavoro e attivi 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à terminare 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 agente. La funzione IS_AGENT_ACTIVATED() di Snowflake restituisce quindi TRUE, il che consente a Snowflake di applicare l'auditing e la governance specifici per l'agente. 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:

Conferma che l'integrazione sia attivata, 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 sia l'endpoint di autorizzazione che quello del token utilizzino l'host dell'account pubblico di Snowflake.

Questo passaggio è necessario solo se la tua organizzazione richiede una policy di rete. Chiedi al tuo responsabile della sicurezza o della rete di approvare gli intervalli di uscita correnti 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 utilizzare indirizzi di uscita di Notion differenti. Se consenti solo l'indirizzo usato durante lo scambio iniziale del token, l'accesso potrebbe riuscire, mentre la convalida o l'aggiornamento del token potrebbero fallire. Utilizza gli intervalli di uscita correnti e approvati di Notion. Non aggiungere un indirizzo IP temporaneo, proveniente da un browser o registrato in un log, alla lista di autorizzazione di produzione.

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 alla rete utente. 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 relativo segreto corrispondente 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 in documentazione, chat, ticket o controllo del codice sorgente.

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 client OAuth, sia che stiano collegando l'MCP di Snowflake a un agente personalizzato o 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 fa questa configurazione:

• Aiuta i membri a trovare il server approvato.

• Memorizza il segreto del client OAuth una volta nell'archivio di connessione crittografato 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.

Una volta che i tuoi amministratori hanno la connessione MCP di Snowflake pronta, ci sono due modi per usarla. Se stai configurando questo per un team, inizia con 11A. Se vuoi solo porre le tue domande, passa alla 11B. Puoi fare entrambe le cose; sono connessioni separate.

Un agente personalizzato offre al tuo team un unico luogo per interrogare i dati di Snowflake. Colleghi Snowflake una volta, aggiungi le istruzioni relative alle tue metriche e tabelle e condividi l'agente con il tuo team. Chiunque lo utilizzi dovrà accedere a Snowflake con le proprie credenziali, in modo che ciascuno ottenga risposte basate esclusivamente sui dati a cui è autorizzato ad accedere.

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 dall'area 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. Rivedi e approva il ruolo Snowflake richiesto.

6. Scegli quali strumenti l'agente può utilizzare. Lascia impostati gli strumenti abilitati alla scrittura e CORTEX_AGENT_RUN in modalità richiesta di approvazione finché non li avrai testati.

7. Seleziona Connetti e conferma che la connessione risulti Connessa.

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. Alcune domande di esempio 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 porre le tue domande nella tua chat, connetti Snowflake al tuo agente di Notion. Accedi con il tuo account Snowflake, così il tuo agente potrà accedere solo ai dati a cui sei autorizzato.

1. Vai su Impostazioni → Notion AI.

2. Sotto Server MCP, seleziona Aggiungi server MCP.

3. Seleziona il server Snowflake etichettato come Gestito dall'area di lavoro. Non selezionare Server MCP personalizzato né inserire l'URL del server manualmente.

4. Seleziona Connetti.

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

6. Rivedi 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.

Dopo esserti connesso, Snowflake appare in Tutte le fonti → Server MCP nella chat.

1. Poni una domanda innocua con una risposta nota che dovrebbe utilizzare 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. Dovrà vedere solo i propri dati, non i tuoi. Questo è il modo più rapido per confermare che l'agente utilizzi l'accesso individuale di ciascuno 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:

• "Da Snowflake, quali sono stati i nostri iscritti totali il mese scorso?"

• "Da 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" una volta che le sue istruzioni chiariscono quando utilizzarlo. Con il tuo Agente Notion, nominare Snowflake aiuta l'agente a scegliere la fonte corretta.

Le richieste di grandi dimensioni possono richiedere più tempo o andare in timeout. Se ciò accade, poni una domanda più specifica o dividi la richiesta in domande più piccole.

Nella maggior parte dei casi, rimani connesso senza fare nulla. Snowflake utilizza token di accesso a breve durata e Notion li aggiorna in background. Un token di accesso in scadenza di per sé non ti disconnetterà.

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 ciascuno è indipendente. Se a qualcuno viene chiesto di accedere nuovamente, ciò non influisce sugli altri, e chi ha creato l'agente non deve fare nulla.

Se stai ruotando il segreto client: Utilizza la rotazione a due segreti di Snowflake invece di sostituire l'integrazione. Mantieni entrambi i segreti validi abbastanza a lungo da aggiornare e testare la configurazione dello spazio di lavoro prima di ritirare quello vecchio.

ALTER SECURITY INTEGRATION <oauth_integration_name>
REFRESH OAUTH_CLIENT_SECRET_2;

• La connessione Snowflake MCP non è elencata. Il tuo amministratore dello spazio di lavoro potrebbe non averla ancora aggiunta, oppure il tuo spazio di lavoro potrebbe limitare i server personalizzati. Chiedi assistenza al tuo 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 etichettato come Workspace Managed.

• 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 utente 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 individuale, per cui utenti con ruoli differenti vedono dati diversi.

• Il Custom Agent funziona nella chat, ma non in un programma. Le esecuzioni programmate e attivate non hanno un utente che ha effettuato l'accesso, quindi non possono ancora utilizzare Snowflake con l'accesso per utente.

• Hai effettuato l'accesso, ma non si connette o gli strumenti non funzionano. L'accesso dimostra chi sei, ma il tuo accesso dipende comunque dai permessi Snowflake. Chiedi al tuo amministratore Snowflake di confermare che il tuo ruolo possa raggiungere il server, il warehouse, l'agente e i dati.

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

• Una richiesta va in timeout. Poni una domanda più specifica o dividi la tua richiesta in domande più piccole.

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 funziona, poi fallisce immediatamente. Il tuo ruolo potrebbe non raggiungere il server, oppure un ruolo o una regola di rete sta bloccando la sessione. Chiedi al tuo amministratore di verificare i tuoi permessi e le tue policy.

• Vedi "Il ruolo ALL richiesto è stato esplicitamente bloccato." La connessione ha richiesto tutti i ruoli contemporaneamente (session:role:all), il che è bloccato. Utilizza invece un ruolo specifico, come session:role:analyst, con il nome del tuo ruolo reale.

• 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 l'URL di reindirizzamento sull'integrazione di sicurezza sul valore esatto di Notion.

• Vedi l'errore 390311 relativo a una sfida di codice 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 il permesso, quindi esegui DESCRIBE MCP SERVER per verificare la configurazione.

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

• Funzionava prima, e ora tutti falliscono dopo una modifica del segreto. Il segreto del client è stato ruotato, quindi la connessione salvata non è aggiornata. Chiedi al tuo amministratore il nuovo segreto, quindi connettiti di nuovo.

• Funzionava prima, e ora fallisce 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. Tali esecuzioni non hanno un utente autenticato, 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 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

• Pratiche di sicurezza per le connessioni degli agenti