设置 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，并开启 Manually configure authentication 和 Use a workspace-shared OAuth client。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 准备就绪后，工作空间所有者或管理员只需为工作空间添加一次服务器。无论成员是将 Snowflake MCP 连接到自定义代理，还是连接到自己的 Notion 代理，都能找到该服务器，而无需查看 OAuth 客户端密钥。

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，并将 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 代理

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