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

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

建立或選擇一個由將執行該伺服器的團隊所擁有的資料庫與架構。

針對受控管的業務問題，您可以公開一個 Cortex 代理程式作為成員使用的工具。它將語意檢視、已驗證的查詢、搜尋與協調功能整合在同一個地方。Cortex 代理程式為選用項目。如果您建立了一個，請使用下方的規格。如果您要替換現有的代理程式，請確保替換後的代理程式符合您已核准的規格。

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

為每個工具提供清晰的名稱與描述。說明它涵蓋哪些資料、結果的詳細程度，以及何時使用它。這有助於代理程式選擇正確的工具。

MCP 伺服器上的 USAGE 權限允許角色連線至伺服器並探索其工具。它不會賦予該角色對倉儲、代理程式、語意瀏覽模式、搜尋服務、預存程序或基礎資料的存取權。請授予該角色對伺服器工具所需之每個資源的存取權限。

僅授予每個工具所需的額外資源存取權限。例如，授予已核准語意瀏覽模式中的 選取、Cortex 搜尋服務上的 USAGE，或在特定函數或程序上授予 USAGE。請勿將角色授予 PUBLIC，也不要為目前或未來的物件新增廣泛的存取權限。

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

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

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

在執行此 SQL 之前，請與您的 Notion 工作空間管理員協調。請其在工作空間 MCP 設定表單中輸入 Snowflake 伺服器 URL，並開啟 手動設定驗證 與 使用工作空間共用 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. 前往工作空間的 Settings。

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

3. 選取 New 工作空間 MCP。

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

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

此設定的作用：

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

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

• 確保成員使用已核准的伺服器 URL、用戶端和範圍登入。

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

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

如果您移除此設定，新成員將無法再找到該伺服器。現有的連接可能仍會顯示，因此請在撤銷 Snowflake 授權並移除現有連接時，一併協調此變更。

一旦您的管理員準備好 Snowflake MCP 連接，就有兩種使用方式。如果您是為團隊進行此設定，請從 11A 開始。如果您只想詢問自己的問題，請跳至 11B。您可以兩者都做；它們是獨立的連接。

自訂代理程式為您的團隊提供了一個詢問 Snowflake 資料的統一窗口。您只需連接一次 Snowflake，加入關於指標與表格的說明，並與團隊共用該代理程式。每位使用者都必須使用自己的憑證登入 Snowflake，因此每個人只能根據他們有權查看的資料獲得答案。

將 Snowflake 連接到自訂代理程式

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

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

3. 選擇 新增連接，然後選擇標記為 工作空間管理 的 Snowflake 伺服器。請勿選擇 自訂 MCP 伺服器 或手動輸入伺服器 URL。

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 伺服器 或手動輸入伺服器 URL。

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，並使用您實際的角色名稱。

• 您看到重新導向錯誤 (錯誤 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 代理程式

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