設定 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 搜尋服務的 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 選項。請返回並改選標記為 工作空間管理 的 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。這些執行沒有使用者登入，因此目前無法透過個別使用者的 Snowflake 登入資訊存取資料。請改在對話中執行請求。

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

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

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

請使用這些 Snowflake 指南來完成設定：

• Snowflake 管理的 MCP 伺服器

• 建立 Snowflake OAuth 安全整合

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

• Snowflake OAuth 概覽

• Snowflake 帳號識別碼

• 自訂代理程式

• 自訂代理程式的 MCP 連接

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

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