設定 Notion 的 Snowflake MCP

你的 自訂代理程式 和 Notion 代理程式 可透過 Snowflake 託管的模型上下文協定（MCP）伺服器連接到 Snowflake。設定完成後，就能向代理程式詢問 Snowflake 資料倉儲中的資料，並直接在 Notion 取得答案。

設定分為多個階段，且每個階段由不同的人員負責：

• Snowflake 管理員 會設定角色、倉儲以及 Snowflake 託管的 MCP 伺服器。

• Notion 工作空間擁有者或管理員 會為工作空間設定 Snowflake MCP 連線。

• 工作空間成員接著可以使用自己的 Snowflake 憑證，從自訂代理程式連接到 Snowflake MCP，或將 Snowflake 直接連接到自己的 Notion 代理程式。本文的步驟 1 至 10 適用於兩種方式；從步驟 11 開始，請依要連接的代理程式選擇對應的操作方式。

• 可用工具可能因 Snowflake 雲端區域而異。

• Snowflake 託管的 MCP 伺服器無法在中國大陸或政府雲端區域使用。

• 你的 Notion 工作空間必須使用商業版或企業版。

• 請使用網頁版或桌面版 Notion。此功能無法在行動裝置上使用。

• 你的公司需要有 Snowflake 帳號。

• 若要建立 自訂代理程式，你需要具備在工作空間建立代理程式的權限。

團隊將 Snowflake 連接到 Notion 前，Snowflake 管理員須先設定存取權限。這是步驟最多的部分，但只需設定一次。請與 Notion 工作空間管理員合作：Notion 提供重新導向 URI，Snowflake 則提供 OAuth 用戶端 ID 和密鑰。

請設定角色與倉儲、建立 Snowflake 託管的 MCP 伺服器、授予伺服器存取所需資源的權限，並設定 OAuth 範圍與安全性整合。如果組織有要求，還需新增網路原則。

開始之前，請與 Notion 工作空間管理員一起填寫這份工作表。成員可跳過這個步驟，待設定完成後再使用自己的 Snowflake 帳號登入。

帳號的主機名稱使用連字號，而非底線。請確認伺服器網址中的每個物件名稱，都與 Snowflake 中對應的物件名稱相符。

請盡可能使用專用的最小權限角色，以及單一已核准的倉儲。

受限角色，不使用次要角色（建議）。這種模型較容易理解與稽核。請設定 OAUTH_USE_SECONDARY_ROLES = NONE、指定 ALLOWED_ROLES_LIST，並使用 Notion 範圍 session:role:<mcp_access_role>。

使用者的預設次要角色（選用）。只有在伺服器需要使用各使用者 Snowflake DEFAULT_SECONDARY_ROLES 繼承的權限時，才選用此模型。請設定 OAUTH_USE_SECONDARY_ROLES = IMPLICIT、省略 ALLOWED_ROLES_LIST，並明確指定主要角色範圍。Snowflake 不允許將 IMPLICIT 次要角色與 ALLOWED_ROLES_LIST 併用，因此選用此模型時，請勿設定允許清單。

請盡可能為 MCP 伺服器使用專用的最小權限角色。

請依標準身分管理流程授予此角色。如果 Snowflake 的角色成員資格由 Okta 或 SCIM 管理，請透過該流程新增使用者，不要自行手動新增。

請建立或選擇由伺服器營運團隊擁有的資料庫與結構描述。

針對受控管的業務問題，可以提供 Cortex Agent 作為成員使用的工具，集中管理語意檢視、已驗證的查詢、搜尋及協調作業。Cortex Agent 並非必要；如果要建立，請使用下方規格。如果要替換現有的代理程式，請確認新代理程式符合已核准的規格。

其他支援的 Snowflake MCP 工具類型包括 CORTEX_ANALYST_MESSAGE、CORTEX_SEARCH_SERVICE_QUERY、GENERIC 以及 SYSTEM_EXECUTE_SQL。

請為每個工具提供清楚的名稱與說明，交代工具涵蓋的資料、結果的詳細程度及適用時機，幫助代理程式選擇合適的工具。

MCP 伺服器的 USAGE 權限可讓角色連接伺服器並探索其中的工具，但不包含倉儲、代理程式、語意檢視、搜尋服務、預存程序或底層資料的存取權限。請另外授予該角色存取伺服器工具所需各項資源的權限。

僅授予各工具存取所需其他資源的權限。例如，授予已核准語意檢視上的 SELECT、Cortex Search 服務上的 USAGE，或特定函數或程序上的 USAGE。請勿將角色授予 PUBLIC，也不要為目前或未來的物件新增廣泛的權限。

在設定 OAuth 之前，請檢查 MCP 伺服器及其授權：

設定 MCP 結構描述以宣告成員應請求的確切角色：

請使用明確的角色範圍。請勿使用 session:role:all。Snowflake 會將該值視為使用者的預設主要角色，而非對每個角色的存取權，且特權角色的原則可能會封鎖它。明確的角色會使請求的存取權限更清晰且更容易檢查。

執行此 SQL 前，請與 Notion 工作空間管理員協調。請管理員在工作空間 MCP 設定表單中輸入 Snowflake 伺服器網址，並開啟 手動設定驗證 和 使用工作空間共享的 OAuth 用戶端。Notion 會產生重新導向 URI。請複製該 URI 並傳送給 Snowflake 管理員。Snowflake 建立用戶端 ID 和密鑰後，工作空間管理員即可完成連接設定。

請完全依照 Notion 提供的重新導向 URI 使用。請勿新增結尾斜線或查詢參數，也不要變更主機。

設定 IS_AGENTIC = TRUE 會將透過此整合建立的工作階段標記為代理程式工作階段。Snowflake 的 IS_AGENT_ACTIVATED() 函數隨後會傳回 TRUE，這讓 Snowflake 能夠套用代理程式專屬的稽核與管控。如果您使用選用的次要角色模型，請設定 OAUTH_USE_SECONDARY_ROLES = IMPLICIT 並省略 ALLOWED_ROLES_LIST。

重新整理權杖的有效期限值 7776000 秒等於 90 天。在使用之前，請確認它符合貴組織的重新授權與權杖輪替政策。對於例行變更，請避免使用 CREATE OR REPLACE SECURITY INTEGRATION。取代整合可能會中斷現有的連接。

若要檢查整合而不顯示其密鑰，請執行：

確認整合已開啟、重新導向 URI 完全相符、角色已獲准且未被封鎖、重新整理權杖與 PKCE 已啟用，且授權與權杖端點皆使用 Snowflake 的公開帳號主機。

此步驟僅在貴組織要求網路原則時才需要。請要求您的安全性或網路負責人核准 Notion 目前的出口範圍。

OAuth 整合必須允許這兩個 Notion 路徑：

1. 處理 OAuth 回呼與交換授權碼的 API 路徑

2. 驗證連接、執行工具並重新整理權杖的工作空間執行階段路徑

這些路徑可能會使用不同的 Notion 出口位址。如果您僅允許初始權杖交換期間使用的位址，登入可能會成功，但驗證或權杖重新整理可能會失敗。請使用 Notion 目前核准的出口範圍。請勿將從瀏覽器或記錄檔取得的一次性 IP 位址新增至正式環境的允許清單。

請將此網路原則附加至 OAuth 整合，而非個別使用者。請勿變更帳號層級的瀏覽器登入、VPN 存取或使用者網路存取原則。如果網路原則封鎖權杖請求，Snowflake 可能會傳回 invalid_client。此錯誤不一定代表用戶端 ID 或密鑰不正確。

請在安全的 Snowflake 工作表中執行此操作。整合名稱區分大小寫，且通常為大寫：

請透過已核准的安全管道，與您的 Notion 工作空間管理員分享用戶端 ID 及其對應的密鑰。Snowflake 提供兩個有效的密鑰，因此您可以輪替它們而無需停機。切勿將任何密鑰貼到文件、對話、工單或原始碼控制系統中。

Snowflake 準備就緒後，工作空間擁有者或管理員只需為工作空間新增一次伺服器。之後，成員無須查看 OAuth 用戶端密鑰就能找到該伺服器，無論是要將 Snowflake MCP 連接至自訂代理程式，還是自己的 Notion 代理程式。

1. 前往工作空間的 設定。

2. 選取 連接 → 工作空間共享的 MCP。

3. 選取 新增工作空間 MCP。

填寫這些欄位，然後選取 新增 MCP 伺服器：

儲存後，請確認新列出現在 與此工作空間共享 下方，且 工作空間 OAuth 用戶端 顯示為 已設定。

此設定的作用：

• 協助成員找到核准的伺服器。

• 只將 OAuth 用戶端祕密金鑰儲存一次，存放於 Notion 的加密連接儲存空間中。

• 確保成員使用你已核准的伺服器網址、用戶端和權限範圍登入。

• 不會建立共用的 Snowflake 工作階段，也不會繞過 Snowflake 的存取控制。

• 不會自動連接每位成員。每個人都必須分別登入。

如果你移除這項設定，新成員就無法再找到該伺服器。現有連接可能仍會顯示，因此移除設定時，也請撤銷 Snowflake 授權並移除現有連接。

管理員準備好 Snowflake MCP 連接後，你有兩種使用方式。如果是為團隊設定，請從 11A 開始；如果只想自己提問，請跳至 11B。兩種方式都可以使用，但需要分別連接。

自訂代理程式讓團隊有一個地方可以詢問 Snowflake 資料。你只需連接一次 Snowflake，加入指標和資料表的相關指示，再將代理程式分享給團隊。每位使用者都必須以自己的憑證登入 Snowflake，因此只能根據自己有權查看的資料取得答案。

將 Snowflake 連接到自訂代理程式

1. 開啟你的自訂代理程式，或建立新的自訂代理程式。

2. 前往 設定 → 工具與存取權。

3. 選取 新增連接，再選擇標示為 工作空間管理 的 Snowflake 伺服器。請使用此選項連接，不要選取 自訂 MCP 伺服器，也不要手動輸入伺服器網址。

4. 在瀏覽器中登入 Snowflake。你可能會看到組織平常使用的 Okta 或單一登入 (SSO) 畫面。

5. 檢閱並核准要求的 Snowflake 角色。

6. 選擇代理程式可使用的工具。完成測試前，請將具備寫入功能的工具和 CORTEX_AGENT_RUN 設為「使用前須經核准」。

7. 選取 連接，並確認連接顯示為 已連接。

為代理程式提供背景資訊

連接後，代理程式就能存取 Snowflake；你提供的指示則能說明公司如何使用這些資料。請在代理程式的指示中，說明各類問題該使用哪些工具、團隊如何定義關鍵指標，以及該從哪些資料表或語意檢視著手。提供幾個經過驗證的範例問題也很有幫助。想快速開始，請參閱 Data Scout 工具組指南。

分享代理程式

和分享其他自訂代理程式一樣，把這個代理程式分享給你的團隊。團隊成員第一次提出需要 Snowflake 才能回答的問題時，系統會提示他們使用自己的 Snowflake 帳號登入，無須輸入用戶端 ID 或祕密金鑰。

如果你想在自己的對話中提問，請將 Snowflake 連接到你的 Notion 代理程式。使用自己的 Snowflake 帳號登入後，代理程式就只能存取你有權查看的內容。

1. 前往 設定 → Notion AI。

2. 在 MCP 伺服器 下，選取 新增 MCP 伺服器。

3. 選取標示為 工作空間管理 的 Snowflake 伺服器。請使用此選項連接，不要選取 自訂 MCP 伺服器，也不要手動輸入伺服器網址。

4. 選取 連接。

5. 在瀏覽器中登入 Snowflake。你可能會看到組織平常使用的 Okta 或單一登入 (SSO) 畫面。

6. 檢閱並核准要求的 Snowflake 角色。

7. 瀏覽器詢問是否開啟 Notion 時，選取 開啟 Notion。

8. 確認伺服器狀態顯示為 已連接，而不是 需要驗證。

連接後，你會在對話的 所有來源 → MCP 伺服器 中看到 Snowflake。

1. 提出一個已知答案、且需要使用 Snowflake 才能回答的簡單問題。

2. 確認代理程式使用 Snowflake 並傳回結果。

3. 確認你無法存取獲指派的角色權限範圍以外的資料。

如果你設定了自訂代理程式，也請 Snowflake 角色權限範圍較小的團隊成員試用。他們應該只能看到自己有權存取的資料，而不是你有權存取的所有資料。這是確認代理程式依每位使用者而非建立者的存取權限提供資料最快的方法。

想進一步確認，請 Snowflake 管理員檢查你的使用者帳號、角色、虛擬倉儲和查詢記錄。成功登入只能確認身分，無法保證每項授權都正確。

向代理程式詢問與你的 Snowflake 資料有關的具體問題。例如：

• 「從 Snowflake 來看，我們上個月的總註冊數是多少？」

• 「根據 Snowflake 的資料，本季營收最高的 10 個客戶帳戶是哪些？」

使用自訂代理程式時，只要指示已明確說明何時使用 Snowflake，提問通常不必再加上「從 Snowflake」。使用 Notion 代理程式時，在問題中提及 Snowflake，則有助於代理程式選對來源。

範圍較廣的請求可能需要較長時間處理，甚至逾時。如果遇到這種情況，請縮小問題範圍，或拆成幾個較小的問題。

大多數時候，你不必做任何事就能維持連接。Snowflake 使用短效存取權杖，Notion 則會在背景更新權杖。存取權杖到期不會直接導致連接中斷。

發生以下情況時，你需要重新登入：

• 你的更新權杖到期，或管理員撤銷該權杖

• 管理員更換 OAuth 整合或用戶端祕密金鑰

• 你的 Snowflake 角色已遭移除

• 管理員移除了工作空間設定或你的連接

• 網路原則封鎖了權杖重新整理

使用自訂代理程式時，每個人的登入都是獨立的。如果其中一人被要求重新登入，這不會影響其他人，且建立代理程式的人員無需執行任何操作。

如果你正在輪替用戶端密鑰： 請使用 Snowflake 的雙密鑰輪替方式，不要更換整合。更新並測試工作空間設定期間，請確保兩組密鑰都保持有效，再停用舊密鑰。

ALTER SECURITY INTEGRATION <oauth_integration_name>
REFRESH OAUTH_CLIENT_SECRET_2;

• 未列出 Snowflake MCP 連接。 工作空間管理員可能尚未新增這項連接，或工作空間限制使用自訂伺服器。請向管理員尋求幫助。

• 系統要求你提供用戶端 ID 或密鑰。 你可能選到了自訂 MCP 選項。請返回，改選標記為 Workspace Managed 的 Snowflake 伺服器。

• 系統要求你重新登入。 你的 Snowflake 工作階段可能已過期，或管理員更新了連接。請重新登入 Snowflake。

• 你開啟自訂代理程式後，系統要求你登入 Snowflake。 第一次使用時出現這項要求是正常的。每位使用受管理自訂代理程式的人，都必須使用自己的 Snowflake 憑證登入。

• 團隊成員使用同一個自訂代理程式，卻得到不同的結果。 這是正常的。代理程式會依照每個人的 Snowflake 存取權限運作，因此不同角色的使用者會看到不同資料。

• 自訂代理程式在對話中運作正常，但透過排程執行時卻無法運作。 排程執行和已觸發的執行都沒有已登入的使用者，因此目前無法透過個人登入使用 Snowflake。

• 你已登入，但仍無法連接，或工具無法正常運作。 登入只是驗證身分，能否存取仍取決於你在 Snowflake 中獲授予的權限。請向 Snowflake 管理員確認你的角色是否能存取伺服器、倉儲、代理程式和資料。

• 代理程式找不到表格。 代理程式只能存取你的 Snowflake 帳號有權存取的資料。請檢查你的 Snowflake 權限，並在問題中附上表格名稱。

• 請求逾時。 請提出更具體的問題，或將請求拆成幾個較小的問題。

這些錯誤通常源自 Snowflake 設定，而非 Notion。請將錯誤資訊分享給你的 Snowflake 管理員。

• 伺服器網址看起來重複了，例如 https://https%3A... 貼上網址時，開頭多了一個 https://。請修正網址，讓開頭只有一個 https://。

• 你看到「此伺服器不支援 OAuth 驗證」。 安全整合可能未設定 OAuth，或伺服器網址有誤。請你的 Snowflake 管理員檢查 OAuth 安全整合和伺服器網址。

• 你在登入或更新時看到 invalid_client。 用戶端 ID 或密鑰可能有誤，或密鑰已變更。請向管理員索取目前的用戶端 ID 和密鑰。

• 登入成功，但隨即失敗。 你的角色可能無法存取伺服器，或有角色或網路規則封鎖了工作階段。請管理員檢查你的授權和原則。

• 你看到「The role ALL requested has been explicitly blocked.」 連接嘗試一次請求所有角色（session:role:all），因此遭到封鎖。請改用單一角色，例如 session:role:analyst，並以你實際使用的角色名稱取代範例中的名稱。

• 你看到重新導向錯誤（錯誤 390307）。 Snowflake 中儲存的重新導向網址與 Notion 使用的網址不符。請管理員將安全整合的重新導向網址設為與 Notion 使用的網址完全一致。

• 你看到關於無效代碼挑戰的錯誤 390311。 這表示 PKCE 設定不符。請管理員確認安全整合中的 OAUTH_ENFORCE_PKCE 設定是否正確。

• 你已連接，但沒有顯示任何工具。 你的角色可能缺少 MCP 伺服器的 USAGE 權限。請管理員確認這項授權，然後執行 DESCRIBE MCP SERVER 檢查設定。

• 你能存取的資料比預期多或少。 次要角色會影響工作階段可存取的資料。請與管理員確認工作階段目前啟用了哪些角色。

• 先前運作正常，但變更密鑰後，所有人都無法連接。 用戶端密鑰已輪替，因此儲存的連接資訊已過期。請向管理員索取新密鑰，然後重新連接。

• 之前運作正常，但現在只有你無法使用。 角色、授權或原則可能已變更，也可能是你的工作階段已過期。請重新登入，再請管理員確認你的存取權限是否有變更。

• 你的帳號識別碼遭到拒絕。 請使用以連字號分隔的 organization-account 格式，例如 myorg-myaccount。

• PrivateLink 帳號無法連接。 PrivateLink 帳號需要額外的網路設定。請向管理員確認 PrivateLink 是否允許連接 Notion。

• Snowflake 無法用於排程執行或已觸發的執行。 這些執行沒有已登入的使用者，因此目前無法使用個人登入功能。請改在對話中執行你的請求。

• 你透過瀏覽器登入後看到 oauth_security_error。 帳號層級的網路原則可能封鎖了這項請求。管理員可以執行以下指令確認：

• 登入似乎成功，但即使範圍正確，仍出現角色錯誤。 你的預設角色可能遭到封鎖，例如 ACCOUNTADMIN 或 BLOCKED_ROLES_LIST 中的角色。管理員可以檢查並修正：

這些唯讀指令可協助管理員確認設定，且不會進行任何變更。請在 Snowflake 中執行這些指令。

請參考以下 Snowflake 指南完成設定：

• Snowflake 管理的 MCP 伺服器

• 建立 Snowflake OAuth 安全整合

• 適用於自訂用戶端的 Snowflake OAuth

• Snowflake OAuth 概覽

• Snowflake 帳號識別碼

• 自訂代理程式

• 自訂代理程式的 MCP 連接

• 將 MCP 伺服器連接至你的 Notion 代理程式

• 代理程式連接的安全性最佳做法