设置 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 帐号登录。

帐号主机名使用连字符，而不是下划线。确保服务器 URL 中的每个对象名称都与 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 服务器 URL，并开启 手动配置身份验证 和 使用工作空间共享的 OAuth 客户端。Notion 会生成重定向 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 工作表中运行此命令。集成名称区分大小写，通常为大写：

通过经批准的安全渠道，将客户端 ID 及其对应的密钥分享给你的 Notion 工作空间管理员。Snowflake 提供两个有效密钥，便于你在不中断服务的情况下轮换密钥。切勿将任一密钥粘贴到文档、对话、工单或版本控制系统中。

一旦 Snowflake 准备就绪，工作空间所有者或管理员即可为该工作空间添加一次服务器。之后，成员无需查看 OAuth 客户端密钥即可找到它，无论他们是将 Snowflake MCP 连接到自定义代理还是他们自己的 Notion 代理。

1. 转到工作空间的 设置。

2. 选择 连接 → 工作空间共享 MCP。

3. 选择 新建工作空间 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 服务器。请返回并选择标记为工作空间托管的 Snowflake 服务器。

• 系统要求你重新登录。你的 Snowflake 会话可能已过期，也可能是管理员更新了连接。请重新登录 Snowflake。

• 你打开自定义代理后，系统要求你登录 Snowflake。首次使用时这是正常的。每位使用托管自定义代理的人员都需要用自己的 Snowflake 登录凭据登录。

• 团队成员使用同一个自定义代理，却得到了不同结果。这是正常的。代理会根据每个人的 Snowflake 访问权限获取数据，因此角色不同，看到的数据也可能不同。

• 自定义代理在对话中可以使用，但按日程运行时无法使用。按日程运行或触发运行时，没有用户登录，因此目前无法通过个人登录来使用 Snowflake。

• 你已登录，但无法连接或工具运行失败。登录只能验证你的身份，访问权限还取决于你在 Snowflake 中获得的授权。请让 Snowflake 管理员确认你的角色能否访问服务器、虚拟仓库、代理和数据。

• 代理找不到数据表。代理只能访问你的 Snowflake 帐号有权访问的数据。请检查 Snowflake 权限，并在问题中注明数据表名称。

• 请求超时。 请提出更具体的问题，或将请求拆分成几个小问题。

这些错误通常与 Snowflake 设置有关，而不是 Notion。请将错误信息发给你的 Snowflake 管理员。

• 服务器 URL 看起来重复了，例如 https://https%3A... 粘贴地址时，前面多加了一个 https://。请删除多余的部分，让 URL 只以一个 https:// 开头。

• 你看到“此服务器不支持 OAuth 验证”。 安全集成可能未配置 OAuth，或者服务器 URL 有误。请让你的 Snowflake 管理员检查 OAuth 安全集成和服务器 URL。

• 你在登录或刷新时看到 invalid_client。 客户端 ID 或密钥可能有误，也可能是密钥已更改。请向你的管理员索取当前的客户端 ID 和密钥。

• 登录成功后，连接立即失败。 你的角色可能无权访问服务器，也可能有角色限制或网络规则阻止了会话。请让你的管理员检查你的授权和策略。

• 你看到“The role ALL requested has been explicitly blocked.” 连接一次请求了所有角色（session:role:all），因此被阻止。请改用一个具体角色，例如 session:role:analyst，并将其中的角色名换成你的实际角色名。

• 你看到重定向错误（错误 390307）。 Snowflake 中保存的重定向 URL 与 Notion 使用的 URL 不匹配。请让你的管理员将安全集成中的重定向 URL 设置为与 Notion 使用的 URL 完全一致。

• 你看到错误 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 代理

• 代理连接的安全最佳实践