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

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

在你的团队将 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 服务器使用专用的、权限最小的角色。

通过你常规的身份管理流程授予此角色。如果 Okta 或 SCIM 管理 Snowflake 角色成员资格，请不要在该流程之外手动添加用户。

创建或选择一个由负责运行该服务器的团队所拥有的数据库和架构。

对于受治理的业务问题，你可以公开一个 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 服务器 URL，并开启 Manually configure authentication 和 Use a workspace-shared OAuth client。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 工作表中运行此命令。集成名称区分大小写，通常为大写：

使用经批准的安全渠道与你的 Notion 工作空间管理员共享客户端 ID 及其匹配的密钥。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 设置为 Notion 的确切值。

• 你看到错误 390311，提示无效代码挑战。 这是一个 PKCE 不匹配。请让你的管理员确认安全集成上 OAUTH_ENFORCE_PKCE 的设置是否正确。

• 你已连接，但没有显示任何工具。 你的角色可能缺少 MCP 服务器上的 USAGE 权限。请让你的管理员确认授权，然后运行 DESCRIBE MCP SERVER 检查设置。

• 你可以访问的数据可能比预期的多或少。 次要角色会影响你会话中能看到的数据。请与你的管理员一起检查哪些角色处于活动状态。

• 以前能正常工作，但现在在密钥变更后所有人都失败了。 客户端密钥已轮换，因此保存的连接已过期。请向你的管理员索取新密钥，然后重新连接。

• 以前能正常工作，但现在只有你失败了。 角色、授权或策略可能已变更，或者你的会话已过期。请重新登录，然后让你的管理员确认你的访问权限未发生变化。

• 你的帐号标识符被拒绝。 请使用带连字符的 organization-account 格式，例如 myorg-myaccount，而不是使用点号。

• PrivateLink 帐号无法连接。 PrivateLink 帐号需要额外的网络设置。请询问你的管理员是否允许 Notion 连接 PrivateLink。

• Snowflake 在计划任务或已触发的运行中不可用。 这些运行没有登录用户，因此无法使用个人登录。请改在对话中运行你的请求。

• 你看到 oauth_security_error 在通过浏览器登录后出现。 账户级网络策略可能阻止了该请求。请让你的管理员通过运行以下命令进行确认：

• 登录似乎成功，但你收到角色错误，即使范围正确。 你的默认角色可能被阻止，例如 ACCOUNTADMIN 或 BLOCKED_ROLES_LIST 中的角色。请让你的管理员检查并修复问题：

这些只读命令可帮助您的管理员在不更改任何内容的情况下确认设置。请在 Snowflake 中运行它们。

使用这些 Snowflake 指南来完成设置：

• Snowflake 管理的 MCP 服务器

• 创建 Snowflake OAuth 安全集成

• 用于自定义客户端的 Snowflake OAuth

• Snowflake OAuth 概述

• Snowflake 帐号标识符

• 自定义代理

• 自定义代理的 MCP 连接

• 将 MCP 服务器连接到你的 Notion 代理

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