Siapkan Snowflake MCP untuk Notion

Agent Kustom dan Notion Agent Anda dapat terhubung ke Snowflake melalui server MCP (Model Context Protocol) yang dijalankan oleh Snowflake. Setelah disiapkan, Anda dapat bertanya kepada agen Anda tentang data gudang Snowflake dan mendapatkan jawaban langsung di Notion.

Penyiapan dilakukan secara bertahap, dan setiap tahap memiliki penanggung jawab yang berbeda:

• Seorang admin Snowflake menyiapkan peran, gudang Snowflake, dan MCP Server yang dikelola oleh Snowflake.

• Seorang pemilik atau admin ruang kerja Notion mengonfigurasi koneksi Snowflake MCP untuk ruang kerja tersebut.

• Anggota ruang kerja kemudian dapat terhubung ke Snowflake MCP dari Agent Kustom menggunakan kredensial Snowflake mereka sendiri, atau menghubungkan Snowflake langsung ke Notion Agent. Langkah 1–10 dari artikel ini sama untuk kedua jalur tersebut. Jalur akan terpisah pada Langkah 11, tergantung pada agen mana yang ingin Anda hubungkan.

• Alat yang tersedia dapat bervariasi tergantung pada wilayah cloud Snowflake Anda.

• MCP Server yang dikelola oleh Snowflake tidak tersedia di Tiongkok daratan atau wilayah pemerintah.

• Ruang kerja Notion Anda harus menggunakan Business atau Enterprise plan.

• Gunakan Notion di web atau desktop. Fitur ini tidak tersedia di perangkat seluler.

• Perusahaan Anda memerlukan akun Snowflake.

• Untuk membuat Agent Kustom, Anda memerlukan izin untuk membuat agen di ruang kerja Anda.

Sebelum tim Anda dapat menghubungkan Snowflake ke Notion, admin Snowflake perlu menyiapkan akses. Ini adalah langkah yang paling rumit, dan Anda hanya perlu melakukannya sekali. Bekerjasamalah dengan admin ruang kerja Notion Anda: Notion menyediakan URI pengalihan, dan Snowflake menyediakan ID klien serta rahasia OAuth.

Anda akan menyiapkan peran dan gudang data, membuat MCP Server yang dikelola oleh Snowflake, memberinya akses ke sumber daya yang diperlukan, mengonfigurasi cakupan OAuth dan integrasi keamanan, serta menambahkan kebijakan jaringan jika organisasi Anda memerlukannya.

Isi worksheet ini bersama admin ruang kerja Notion Anda sebelum Anda memulai. Anggota dapat melewatinya dan masuk dengan akun Snowflake mereka sendiri setelah penyiapan selesai.

Nama host akun menggunakan tanda hubung, bukan garis bawah. Pastikan setiap nama objek di URL server cocok dengan nama objek yang sesuai di Snowflake.

Gunakan peran khusus dengan hak istimewa paling rendah dan satu gudang data yang disetujui jika memungkinkan.

Peran terbatas tanpa peran sekunder (disarankan). Model ini lebih mudah dipahami dan diaudit. Tetapkan OAUTH_USE_SECONDARY_ROLES = NONE, tentukan ALLOWED_ROLES_LIST, dan gunakan cakupan Notion session:role:<mcp_access_role>.

Peran sekunder default pengguna (opsional). Gunakan model ini hanya jika server memerlukan hak istimewa yang diwarisi dari DEFAULT_SECONDARY_ROLES Snowflake setiap pengguna. Tetapkan OAUTH_USE_SECONDARY_ROLES = IMPLICIT, hilangkan ALLOWED_ROLES_LIST, dan gunakan cakupan peran utama eksplisit. Snowflake tidak mengizinkan peran sekunder IMPLICIT dengan ALLOWED_ROLES_LIST, jadi hilangkan daftar izin saat Anda menggunakan model ini.

Gunakan peran khusus dengan hak istimewa paling rendah untuk MCP Server jika memungkinkan.

Berikan peran ini melalui proses manajemen identitas Anda yang biasa. Jika Okta atau SCIM mengelola keanggotaan peran Snowflake, jangan tambahkan pengguna secara manual di luar proses tersebut.

Buat atau pilih database dan skema yang dimiliki oleh tim yang akan memproses MCP Server.

Untuk pertanyaan bisnis yang diatur, Anda dapat mengekspos Agen Cortex sebagai alat yang digunakan anggota. Ini menyimpan tampilan semantik, kueri terverifikasi, Pencarian, dan orkestrasi di satu tempat. Agen Cortex bersifat opsional. Jika Anda membuatnya, gunakan spesifikasi di bawah ini. Jika Anda mengganti agen yang sudah ada, pastikan penggantinya sesuai dengan spesifikasi yang Anda setujui.

Jenis alat MCP Snowflake lain yang didukung mencakup CORTEX_ANALYST_MESSAGE, CORTEX_SEARCH_SERVICE_QUERY, GENERIC, dan SYSTEM_EXECUTE_SQL.

Berikan nama dan deskripsi yang jelas untuk setiap alat. Jelaskan data apa yang dicakupnya, seberapa rinci hasilnya, dan kapan harus menggunakannya. Ini membantu agen memilih alat yang tepat.

Hak istimewa USAGE pada server MCP memungkinkan peran untuk terhubung ke server dan menemukan alat-alatnya. Hak ini tidak memberikan peran akses ke gudang data, agen, tampilan semantik, layanan Pencarian, prosedur tersimpan, atau data yang mendasarinya. Berikan peran tersebut akses ke setiap sumber daya yang dibutuhkan oleh alat server.

Berikan akses hanya ke sumber daya tambahan yang dibutuhkan oleh setiap alat. Misalnya, berikan SELECT pada tampilan semantik yang disetujui, USAGE pada layanan Cortex Search, atau USAGE pada fungsi atau prosedur tertentu. Jangan berikan peran tersebut ke PUBLIC atau tambahkan hak istimewa yang luas untuk objek saat ini atau di masa mendatang.

Sebelum menyiapkan OAuth, periksa MCP Server dan hak istimewanya:

Konfigurasikan skema MCP untuk mengiklankan peran yang tepat yang harus diminta oleh anggota:

Gunakan cakupan peran eksplisit. Jangan gunakan session:role:all. Snowflake memperlakukan nilai tersebut sebagai peran utama default pengguna, bukan sebagai akses ke setiap peran, dan kebijakan untuk peran istimewa mungkin memblokirnya. Peran eksplisit membuat akses yang diminta menjadi jelas dan lebih mudah diperiksa.

Sebelum menjalankan SQL ini, koordinasikan dengan admin ruang kerja Notion Anda. Minta mereka untuk memasukkan URL server Snowflake di Forms pengaturan MCP ruang kerja dan aktifkan Manually configure authentication dan Use a workspace-shared OAuth client. Notion akan membuat URI pengalihan. Salin URI tersebut dan kirimkan ke admin Snowflake. Setelah Snowflake membuat ID klien dan rahasia, admin ruang kerja dapat menyelesaikan pengaturan koneksi.

Gunakan URI pengalihan persis seperti yang disediakan oleh Notion. Jangan tambahkan garis miring atau parameter kueri di akhir, dan jangan ubah host-nya.

Mengatur IS_AGENTIC = TRUE menandai sesi yang dibuat melalui integrasi ini sebagai sesi agen. Fungsi IS_AGENT_ACTIVATED() Snowflake kemudian mengembalikan TRUE, yang memungkinkan Snowflake menerapkan audit dan governance khusus agen. Jika Anda menggunakan model peran sekunder opsional, atur OAUTH_USE_SECONDARY_ROLES = IMPLICIT dan hilangkan ALLOWED_ROLES_LIST.

Nilai validitas token penyegaran 7776000 detik setara dengan 90 hari. Sebelum menggunakannya, pastikan nilai tersebut sesuai dengan kebijakan otorisasi ulang dan rotasi token organisasi Anda. Untuk perubahan rutin, hindari CREATE OR REPLACE SECURITY INTEGRATION. Mengganti integrasi dapat mengganggu koneksi yang ada.

Untuk memeriksa integrasi tanpa menampilkan rahasianya, jalankan:

Pastikan integrasi diaktifkan, URI pengalihan cocok persis, peran diizinkan dan tidak diblok, token penyegaran dan PKCE aktif, serta titik akhir otorisasi dan token menggunakan host akun publik Snowflake.

Langkah ini hanya diperlukan jika organisasi Anda mewajibkan kebijakan jaringan. Minta pemilik keamanan atau jaringan Anda untuk menyetujui rentang egress Notion saat ini.

Integrasi OAuth harus mengizinkan kedua jalur Notion berikut:

1. jalur API yang menangani panggilan balik OAuth dan pertukaran kode otorisasi

2. jalur runtime ruang kerja yang memvalidasi koneksi, memproses alat, dan menyegarkan token

Jalur-jalur ini mungkin menggunakan alamat egress Notion yang berbeda. Jika Anda hanya mengizinkan alamat yang digunakan selama pertukaran token awal, proses masuk mungkin berhasil, tetapi validasi atau penyegaran token mungkin gagal. Gunakan rentang egress Notion yang saat ini disetujui. Jangan tambahkan alamat IP satu kali dari browser atau log ke daftar izin produksi.

Lampirkan kebijakan jaringan ini ke integrasi OAuth, bukan ke pengguna individu. Jangan ubah kebijakan seluruh akun Anda untuk masuk peramban, akses VPN, atau akses jaringan pengguna. Jika kebijakan jaringan memblokir permintaan token, Snowflake mungkin mengembalikan invalid_client. Kesalahan ini tidak selalu berarti ID klien atau rahasia salah.

Jalankan ini di lembar kerja Snowflake yang aman. Nama integrasi bersifat peka huruf besar-kecil dan biasanya menggunakan huruf besar:

Bagikan ID klien dan rahasia yang cocok dengan admin ruang kerja Notion Anda menggunakan saluran aman yang disetujui. Snowflake menyediakan dua rahasia yang valid, sehingga Anda dapat merotasinya tanpa waktu henti. Jangan pernah menempelkan rahasia apa pun ke dalam dokumentasi, obrolan, tiket, atau kontrol sumber.

Setelah Snowflake siap, pemilik atau admin ruang kerja menambahkan server satu kali untuk ruang kerja tersebut. Anggota kemudian dapat menemukannya tanpa melihat rahasia klien OAuth, baik saat mereka menghubungkan MCP Snowflake ke Agen Kustom atau ke Notion Agent mereka sendiri.

1. Buka Pengaturan untuk ruang kerja tersebut.

2. Pilih Koneksi → MCP yang dibagikan ruang kerja.

3. Pilih MCP ruang kerja baru.

Isi kolom-kolom ini, lalu pilih Tambahkan server MCP:

Setelah Anda menyimpan, pastikan baris baru muncul di bawah Dibagikan dengan ruang kerja ini dan bahwa Klien OAuth ruang kerja menampilkan Configured.

Apa yang dilakukan pengaturan ini:

• Membantu anggota menemukan server yang disetujui.

• Menyimpan rahasia klien OAuth satu kali di penyimpanan koneksi terenkripsi Notion.

• Memastikan anggota masuk dengan URL server, klien, dan cakupan yang Anda setujui.

• Tidak membuat sesi Snowflake bersama atau melewati kontrol akses Snowflake.

• Tidak menghubungkan setiap anggota secara otomatis. Setiap orang harus masuk secara terpisah.

Jika Anda menghapus pengaturan ini, anggota baru tidak dapat lagi menemukan server. Koneksi yang ada mungkin masih muncul, jadi koordinasikan perubahan ini dengan mencabut hak akses Snowflake dan menghapus koneksi yang ada.

Setelah admin Anda menyiapkan koneksi MCP Snowflake, ada dua cara untuk menggunakannya. Jika Anda menyiapkan ini untuk tim, mulailah dengan 11A. Jika Anda hanya ingin mengajukan pertanyaan sendiri, lewati ke 11B. Anda dapat melakukan keduanya; keduanya adalah koneksi terpisah.

Agent Kustom memberikan tim Anda satu tempat untuk bertanya tentang data Snowflake. Anda menghubungkan Snowflake sekali, menambahkan instruksi tentang metrik dan tabel Anda, lalu membagikan agen tersebut kepada tim Anda. Setiap orang yang menggunakannya akan diminta untuk masuk ke Snowflake dengan kredensial mereka sendiri, sehingga setiap orang hanya mendapatkan jawaban berdasarkan data yang diizinkan untuk mereka lihat.

Hubungkan Snowflake ke Agent Kustom

1. Buka Agent Kustom Anda, atau buat yang baru.

2. Buka Pengaturan → Alat & Akses.

3. Pilih Tambahkan koneksi, lalu pilih server Snowflake yang diberi label Workspace Managed. Jangan pilih Custom MCP server atau memasukkan URL server secara manual.

4. Masuk ke Snowflake di browser Anda. Login Okta atau SSO organisasi Anda yang biasa mungkin akan muncul.

5. Tinjau dan setujui peran Snowflake yang diminta.

6. Pilih alat mana yang dapat digunakan oleh agen. Biarkan alat yang mampu menulis dan CORTEX_AGENT_RUN diatur untuk meminta persetujuan sampai Anda mengujinya.

7. Pilih Hubungkan, dan konfirmasikan bahwa koneksi ditampilkan sebagai Terhubung.

Berikan konteks pada agen

Koneksi ini memberikan agen akses ke Snowflake. Instruksi Anda memberitahu agen bagaimana perusahaan Anda menggunakan data tersebut. Dalam Instruksi agen, jelaskan alat mana yang harus digunakan untuk jenis pertanyaan tertentu, bagaimana tim Anda mendefinisikan metrik utama, dan tabel atau tampilan semantik mana yang harus dijadikan titik awal. Beberapa contoh pertanyaan yang terverifikasi akan sangat membantu. Untuk titik awal yang sudah jadi, lihat panduan toolkit Data Scout.

Bagikan agen

Bagikan agen tersebut kepada tim Anda dengan cara yang sama seperti Anda membagikan Agent Kustom lainnya. Saat seseorang pertama kali mengajukan pertanyaan yang memerlukan Snowflake, mereka akan diminta untuk masuk dengan akun Snowflake mereka sendiri. Mereka tidak akan dimintai ID klien atau rahasia.

Jika Anda ingin mengajukan pertanyaan sendiri dalam obrolan Anda sendiri, hubungkan Snowflake ke Notion Agent Anda. Anda masuk dengan akun Snowflake Anda sendiri, sehingga agen Anda hanya menjangkau apa yang diizinkan untuk Anda lihat.

1. Buka Pengaturan → Notion AI.

2. Di bawah MCP Server, pilih Tambahkan MCP Server.

3. Pilih server Snowflake yang diberi label Workspace Managed. Jangan pilih Custom MCP server atau memasukkan URL server secara manual.

4. Pilih Hubungkan.

5. Masuk ke Snowflake di browser Anda. Mungkin akan muncul tampilan masuk Okta atau SSO dari organisasi Anda.

6. Tinjau dan setujui peran Snowflake yang diminta.

7. Saat browser Anda menanyakan apakah akan membuka Notion, pilih Buka Notion.

8. Pastikan status server adalah Tersambung, bukan Perlu autentikasi.

Setelah Anda tersambung, Snowflake muncul di Semua sumber → MCP Server dalam obrolan.

1. Ajukan pertanyaan yang tidak berbahaya dengan jawaban yang diketahui yang seharusnya menggunakan Snowflake.

2. Pastikan agen menggunakan Snowflake dan mengembalikan hasil.

3. Pastikan Anda tidak dapat mengakses data di luar peran yang diberikan kepada Anda.

Jika Anda menyiapkan Agen Kustom, mintalah juga rekan tim dengan peran Snowflake yang lebih terbatas untuk mencobanya. Mereka seharusnya hanya melihat data mereka sendiri, bukan data Anda. Itu adalah cara tercepat untuk memastikan agen menggunakan akses setiap orang, bukan akses pembuatnya.

Untuk pemeriksaan lebih mendalam, mintalah admin Snowflake Anda untuk mengonfirmasi pengguna, peran, gudang, dan riwayat kueri Anda. Masuk yang berhasil mengonfirmasi identitas Anda, tetapi tidak mengonfirmasi bahwa setiap pemberian hak akses sudah benar.

Ajukan pertanyaan spesifik kepada agen mengenai data Snowflake Anda. Contohnya:

• "Dari Snowflake, berapa total pendaftaran kita bulan lalu?"

• "Dari Snowflake, apa 10 akun dengan pendapatan tertinggi kita kuartal ini?"

Dengan Agen Kustom, Anda biasanya dapat melewati "dari Snowflake" setelah instruksinya memperjelas kapan harus menggunakannya. Dengan Notion Agent Anda, menyebutkan Snowflake membantu agen memilih sumber yang tepat.

Permintaan besar bisa memakan waktu lebih lama atau mengalami waktu habis. Jika itu terjadi, ajukan pertanyaan yang lebih sempit atau bagi permintaan menjadi pertanyaan yang lebih kecil.

Sebagian besar waktu, Anda tetap tersambung tanpa melakukan apa pun. Snowflake menggunakan token akses berumur pendek, dan Notion menyegarkannya di latar belakang. Token akses yang kedaluwarsa dengan sendirinya tidak akan memutuskan sambungan Anda.

Anda perlu masuk kembali jika:

• Token penyegaran Anda kedaluwarsa atau admin mencabutnya

• Admin mengganti integrasi OAuth atau rahasia klien

• Peran Snowflake Anda dihapus

• Admin menghapus pengaturan ruang kerja atau koneksi Anda

• Kebijakan jaringan memblokir penyegaran token

Dengan Agen Kustom, masuk setiap orang terpisah. Jika satu orang diminta untuk masuk lagi, itu tidak memengaruhi orang lain, dan orang yang membuat agen tidak perlu melakukan apa pun.

Jika Anda merotasi rahasia klien: Gunakan rotasi dua rahasia Snowflake alih-alih mengganti integrasi. Jaga agar kedua rahasia tetap valid cukup lama untuk memperbarui dan menguji pengaturan ruang kerja sebelum menghentikan yang lama.

ALTER SECURITY INTEGRATION <oauth_integration_name>
REFRESH OAUTH_CLIENT_SECRET_2;

• Admin ruang kerja Anda mungkin belum menambahkannya, atau ruang kerja Anda mungkin membatasi server kustom. Minta bantuan admin Anda.

• Anda diminta untuk ID klien atau rahasia. Anda mungkin telah memilih opsi MCP kustom. Kembali dan pilih MCP Server yang ditandai Workspace Managed sebagai gantinya.

• Anda diminta untuk masuk lagi. Sesi Snowflake Anda mungkin telah kedaluwarsa, atau admin mungkin telah memperbarui koneksi. Masuk ke Snowflake lagi.

• Anda membuka Agent Kustom dan diminta untuk masuk ke Snowflake. Itu wajar saat pertama kali. Setiap orang yang menggunakan Agent Kustom terkelola diharuskan masuk dengan kredensial Snowflake mereka sendiri.

• Rekan tim mendapatkan hasil yang berbeda dari Agent Kustom yang sama. Itu wajar. Agent menggunakan akses Snowflake masing-masing orang, jadi orang dengan peran berbeda melihat data yang berbeda.

• Agent Kustom berfungsi di obrolan tetapi tidak pada Jadwal. Proses yang dijadwalkan dan terpicu tidak memiliki pengguna yang masuk, sehingga belum dapat menggunakan Snowflake dengan masuk per orang.

• Anda sudah masuk, tetapi tidak dapat terhubung atau alat gagal. Masuk membuktikan siapa Anda, tetapi akses Anda masih bergantung pada hibah Snowflake Anda. Minta admin Snowflake Anda untuk mengonfirmasi bahwa peran Anda dapat menjangkau server, gudang, agen, dan data.

• Agen tidak dapat menemukan tabel. Agen hanya dapat menjangkau data yang dapat dijangkau oleh akun Snowflake Anda. Periksa izin Snowflake Anda, dan sertakan nama tabel dalam pertanyaan Anda.

• Permintaan kehabisan waktu. Ajukan pertanyaan yang lebih spesifik, atau bagi permintaan Anda menjadi pertanyaan yang lebih kecil.

Kesalahan ini biasanya berasal dari pengaturan Snowflake, bukan Notion. Bagikan kesalahan tersebut dengan admin Snowflake Anda.

• URL server terlihat ganda, seperti https://https%3A... Alamat ditempel dengan https:// tambahan di depan. Perbaiki agar URL dimulai dengan hanya satu https://.

• Anda melihat "This server does not support OAuth authentication." Integrasi keamanan tidak disiapkan untuk OAuth, atau URL server salah. Minta admin Snowflake Anda untuk memeriksa integrasi keamanan OAuth dan URL server.

• Anda melihat invalid_client saat masuk atau menyegarkan. ID klien atau rahasia salah, atau rahasia telah diubah. Minta admin Anda untuk mendapatkan ID klien dan rahasia saat ini.

• Masuk berhasil, lalu langsung gagal. Peran Anda mungkin tidak mencapai server, atau peran atau aturan jaringan memblokir sesi tersebut. Minta admin Anda untuk memeriksa pemberian hak akses dan kebijakan Anda.

• Anda melihat "Peran ALL yang diminta telah diblok secara eksplisit." Koneksi meminta setiap peran sekaligus (session:role:all), yang diblok. Gunakan satu peran yang tepat sebagai gantinya, seperti session:role:analyst, dengan nama peran asli Anda.

• Anda melihat kesalahan pengalihan (kesalahan 390307). URL pengalihan yang disimpan di Snowflake tidak cocok dengan yang digunakan Notion. Minta admin Anda untuk menetapkan URL pengalihan pada integrasi keamanan ke nilai Notion yang tepat.

• Anda melihat kesalahan 390311 tentang tantangan kode yang tidak valid. Ini adalah ketidakcocokan PKCE. Minta admin Anda untuk mengonfirmasi OAUTH_ENFORCE_PKCE telah diatur dengan benar pada integrasi keamanan.

• Anda terhubung, tetapi tidak ada alat yang muncul. Peran Anda mungkin tidak memiliki USAGE pada MCP Server. Minta admin Anda untuk mengonfirmasi pemberian hak akses, lalu jalankan DESCRIBE MCP SERVER untuk memeriksa pengaturan.

• Anda dapat menjangkau lebih banyak atau lebih sedikit data daripada yang Anda harapkan. Peran sekunder mengubah apa yang dapat dilihat oleh sesi Anda. Periksa peran mana yang aktif dalam sesi Anda bersama admin Anda.

• Sebelumnya berhasil, dan sekarang semua orang gagal setelah perubahan rahasia. Rahasia klien dirotasi, sehingga koneksi yang disimpan sudah kedaluwarsa. Minta rahasia baru kepada admin Anda, lalu hubungkan kembali.

• Sebelumnya berhasil, dan sekarang gagal hanya untuk Anda. Peran, pemberian hak akses, atau kebijakan mungkin telah berubah, atau sesi Anda kedaluwarsa. Masuk kembali, lalu minta admin Anda untuk mengonfirmasi bahwa akses Anda tidak berubah.

• Pengidentifikasi akun Anda ditolak. Gunakan format organization-account dengan tanda hubung, seperti myorg-myaccount, bukan titik.

• Akun PrivateLink tidak dapat terhubung. Akun PrivateLink memerlukan pengaturan jaringan tambahan. Tanyakan kepada admin Anda apakah PrivateLink mengizinkan koneksi Notion.

• Snowflake tidak tersedia dalam proses yang dijadwalkan atau dipicu. Proses tersebut tidak memiliki pengguna yang masuk, sehingga belum dapat menggunakan masuk per pengguna. Jalankan permintaan Anda di obrolan sebagai gantinya.

• Anda melihat oauth_security_error setelah masuk melalui browser. Kebijakan jaringan tingkat akun mungkin memblokir permintaan tersebut. Admin Anda dapat mengonfirmasi dengan menjalankan:

• Masuk tampaknya berhasil tetapi Anda mendapatkan kesalahan peran, bahkan dengan cakupan yang tepat. Peran default Anda mungkin diblokir, misalnya ACCOUNTADMIN atau peran dalam BLOCKED_ROLES_LIST. Admin Anda dapat memeriksa dan memperbaikinya:

Perintah khusus baca ini membantu admin Anda mengonfirmasi pengaturan tanpa mengubah apa pun. Jalankan perintah tersebut di Snowflake.

Gunakan panduan Snowflake ini untuk menyelesaikan pengaturan:

• Server MCP yang dikelola Snowflake

• Membuat integrasi keamanan OAuth Snowflake

• OAuth Snowflake untuk klien kustom

• Ikhtisar OAuth Snowflake

• Pengidentifikasi akun Snowflake

• Agent Kustom

• Koneksi MCP untuk Agent Kustom

• Hubungkan server MCP ke Notion Agent Anda

• Praktik terbaik keamanan untuk koneksi Agent