設定 Notion 的 Snowflake MCP

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

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

• 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 伺服器使用專用、權限最小化的角色。

透過您的標準身分管理流程授予此角色。如果 Okta 或 SCIM 管理 Snowflake 角色成員資格，請勿在該流程之外手動新增使用者。

建立或選擇一個資料庫和結構描述，交由負責執行伺服器的團隊擁有。

如果要處理須遵循資料治理規範的業務問題，你可以將 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 目前的對外連線 IP 位址範圍。

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

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

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

這些路徑可能使用不同的 Notion 對外連線位址。如果只允許初次交換權杖時使用的位址，登入可能成功，但連接驗證或權杖重新整理可能失敗。請使用 Notion 目前已核准的對外連線 IP 位址範圍。不要將從瀏覽器或記錄檔取得的單次 IP 位址加入正式環境的允許清單。

請將此網路原則套用至 OAuth 整合，而非個別使用者。不要變更帳號整體適用的瀏覽器登入、VPN 存取或使用者網路存取原則。如果網路原則封鎖權杖請求，Snowflake 可能傳回 invalid_client。這不一定代表用戶端 ID 或密鑰有誤。

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

請透過已核准的安全管道，將用戶端 ID 和對應密鑰分享給 Notion 工作空間管理員。Snowflake 提供兩組有效密鑰，方便你在不中斷服務的情況下輪替。切勿將密鑰貼到文件、對話、工單或原始碼控制系統。

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

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

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

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

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

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

這項設定的作用

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

• 將 OAuth 用戶端密鑰儲存在 Notion 的加密連接儲存空間中，只需設定一次。

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

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

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

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

管理員準備好 Snowflake MCP 連接後，你可以透過 2 種方式使用。如果要為團隊設定，請從 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 資料，請將 Snowflake 連接到你的 Notion 代理程式。使用自己的 Snowflake 帳號登入後，代理程式只能存取你有權查看的資料。

1. 前往 設定 → Notion AI。

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

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

4. 選取 連接。

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

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

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

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

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

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，並將 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 代理程式

• 代理程式連接的安全性最佳實踐