设置 Notion 的 Snowflake MCP

你的 自定义代理 和 Notion 代理 可以通过 Snowflake 运行的 MCP（大模型上下文协议） 服务器连接到 Snowflake。设置完成后，你可以向代理询问有关 Snowflake 仓库数据的问题，并直接在 Notion 中获得答案。

设置分阶段进行，每个阶段由不同的人员负责：

• Snowflake 管理员 设置角色、仓库和 Snowflake 托管的 MCP 服务器。

• Notion 工作空间所有者或管理员 为工作空间配置 Snowflake MCP 连接。

• 工作空间成员随后可以用自己的 Snowflake 凭据，通过自定义代理连接 Snowflake MCP，也可以将 Snowflake 直接连接到自己的 Notion 代理。两种方式的前 10 步相同。从第 11 步开始，根据你要连接的代理选择对应步骤。

• 可用的工具可能因你的 Snowflake 云区域而异。

• Snowflake 托管的 MCP 服务器在中国大陆和政府云区域不可用。

• 你的 Notion 工作空间需要使用商业版或企业版。

• 请在网页版或桌面版 Notion 上使用。此功能在移动端不可用。

• 你的公司需要一个 Snowflake 帐号。

• 要构建 自定义代理，你需要有在工作空间中创建代理的权限。

在你的团队将 Snowflake 连接到 Notion 之前，Snowflake 管理员需要设置访问权限。这是最复杂的一步，且只需执行一次。请与你的 Notion 工作空间管理员协作：Notion 提供重定向 URI，Snowflake 提供 OAuth 客户端 ID 和密钥。

你将设置角色和虚拟仓库，创建 Snowflake 托管的 MCP 服务器，授予其所需资源的访问权限，配置 OAuth 范围和安全集成，并在组织有要求时添加网络策略。

设置完成后，成员无需填写此工作表，可以直接用自己的 Snowflake 帐号登录。开始前，请先与你的 Notion 工作空间管理员一起填写此工作表。

帐号主机名使用连字符，不使用下划线。请确保服务器 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。拷贝该 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 和密钥。

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

• 你看到“请求的角色 ALL 已被明确阻止”。 此连接一次请求了所有角色（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 代理

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