snowmcpaz (Miguel El Gallo)

雪人水晶

VS Code扩展，通过本地Node.js代理公开Snowflake管理的MCP服务器，并使用从Azure CLI获取的Microsoft Entra访问令牌对请求进行身份验证。

角色快捷方式：

• 最终用户
• Entra管理员
• 雪花管理员
• 故障排除

概述

扩展有四件事：

• 在VS代码中注册MCP服务器定义
• 启动本地Node.js stdio代理
• 通过以下方式获取访问令牌 az account get-access-token
• 将JSON-RPC调用转发到Snowflake MCP端点

该扩展不会创建您的Entra应用程序注册、Snowflake MCP服务器、外部OAuth集成、用户映射或角色授予。

这些部分必须已经存在，扩展才能工作。

建筑

flowchart LR
		user["VS Code user"] --> vscode["VS Code extension"]
		vscode --> broker["Local MCP broker"]
		broker --> az["Azure CLI"]
		az --> entra["Microsoft Entra app\napi://"]
		broker --> snowflake["Snowflake MCP endpoint"]
		snowflake --> broker

谁做什么

先决条件清单

在使用扩展之前，请确认所有这些都是真的。

• Entra应用程序注册存在，并使用基于应用程序（客户端）ID的真实应用程序ID URI，而不是显示名称。
• 该应用程序公开了委托范围 session:role-any.
• Azure CLI已预先授权该应用程序注册。
• 租户同意已处理。
• 雪花MCP服务器已存在。
• Snowflake外部OAuth集成信任相同的Entra应用程序受众。
• Snowflake可以将令牌声明映射到目标用户。
• 所选Snowflake角色已授予用户，并且对外部OAuth有效。

如果您需要管理程序，请使用接下来的两部分。

面向终端用户的快速入门

只有在满足上述清单后才能使用此路径。

1. 安装Azure CLI并使用拥有Entra应用程序的租户登录。
2. 集 snowflakeMcp.endpointUrl, snowflakeMcp.azureAppIdUri，以及 snowflakeMcp.role 在VS代码中。
3. 可选设置 snowflakeMcp.azureTenantId 如果你需要强制特定的租户。
4. 离开 snowflakeMcp.useAzureCli 着手 true.
5. 跑 Snowflake MCP: Refresh Azure Token.
6. 跑 Snowflake MCP: Test Connection.

如果您还没有以下四个值，请停在这里询问您的Entra和Snowflake管理员。这 谁做什么 表显示了他们必须完成的设置。

• 雪花MCP端点URL
• 例如，Entra应用程序ID URI api://e78b3971-ac83-4da7-ba8e-c99e42e5e8b9
• 要发送的雪花角色 X-Snowflake-Role
• 如果您的组织需要租户锁定，则显示租户ID

Entra管理员

Entra方面很小，但很严格。用户只需要获取令牌就可以为一个受众工作，并且该扩展完全依赖于Azure CLI来实现该运行时流。

所需的应用程序注册形状：

• 登录受众：通常是单租户
• 应用程序ID URI: api://
• 委托范围： session:role-any
• Azure CLI预先授权为授权客户端应用程序

Azure CLI客户端ID:

04b07795-8ddb-461a-bbee-02f9e1bf7b46

预授权门户位置：

• 应用程序注册
• 您的应用程序
• 公开API
• 授权客户端应用程序

推荐给用户的切换：

• 租户ID
• 应用程序ID URI
• 用户是否必须使用特定租户登录

详细的管理员检查表： ENTRA_ADMIN_CHECKLIST.md

对于Snowflake管理员

在引入扩展之前，Snowflake必须已经能够接受Entra令牌。

创建授权集成

这是强制性的。

Snowflake管理员必须创建一个外部OAuth授权集成，在Snowflake中作为安全集成公开，然后任何用户都可以使用此扩展进行身份验证。

如果没有这种整合：

• Snowflake不信任Entra发行的代币
• 象征性的观众永远无法匹配
• 用户声明无法映射到Snowflake用户
• 即使Azure CLI令牌获取成功，扩展连接测试也会失败

至少，这种整合必须定义：

• Entra发行人雪花应该信任
• JWKS URL Snowflake用于验证令牌签名
• 包含确切Entra应用程序ID URI的受众列表
• 用户映射声明和Snowflake用户属性
• EXTERNAL_OAUTH_ANY_ROLE_MODE = 'ENABLE' 如果您希望请求的角色标头正常工作

所需设置

• 创建MCP服务器。
• 创建外部OAuth安全集成。
• 配置令牌受众和发行者以匹配Entra。
• 集 EXTERNAL_OAUTH_ANY_ROLE_MODE = 'ENABLE' 因此可以在请求时选择所请求的角色。
• 将用户声明映射到真正的Snowflake用户。
• 授予具有以下条件的角色 USAGE 在数据库、模式和MCP服务器上。

端点形状示例：

https://.snowflakecomputing.com/api/v2/databases//schemas//mcp-servers/

不追加 /mcp.

参考外部OAuth形状：

CREATE OR REPLACE SECURITY INTEGRATION azure_oauth_mcp
	TYPE = EXTERNAL_OAUTH
	ENABLED = TRUE
	EXTERNAL_OAUTH_TYPE = AZURE
	EXTERNAL_OAUTH_ISSUER = 'https://sts.windows.net//'
	EXTERNAL_OAUTH_JWS_KEYS_URL = 'https://login.microsoftonline.com//discovery/v2.0/keys'
	EXTERNAL_OAUTH_TOKEN_USER_MAPPING_CLAIM = 'email'
	EXTERNAL_OAUTH_SNOWFLAKE_USER_MAPPING_ATTRIBUTE = 'email_address'
	EXTERNAL_OAUTH_ANY_ROLE_MODE = 'ENABLE'
	EXTERNAL_OAUTH_AUDIENCE_LIST = ('api://');

访客用户备注：

• email 映射通常比 upn 对于访客用户。
• 只有当令牌 email 索赔与Snowflake用户的索赔相匹配 EMAIL 属性。
• 如果 email 在您的租户中不可靠，请验证是否 upn 在切换之前，映射可用于所有预期用户。

角色说明：

• 不要计划 ACCOUNTADMIN 对于这种流动。
• 尽可能使用特权最低的角色。
• 使用验证当前集成设置 DESC SECURITY INTEGRATION azure_oauth_mcp;.

调试VS代码前验证

此序列从扩展外部验证身份验证链。

1.获取Azure CLI会话

az login

如果尚未行使租户同意，而您的政策允许：

az login --scope "api:///session:role-any" --allow-no-subscriptions

2.验证令牌获取

az account get-access-token --resource "api://" --output json

外延首先尝试现代范围形式，然后回落到 --resource。如果上述命令失败，扩展也将失败。

3.检查重要索赔

在已发布的令牌中确认这些声明：

• aud 火柴 api://
• iss 与Snowflake集成发行者匹配
• scp 包含 session:role-any
• email 如果使用电子邮件映射，则与Snowflake用户匹配

如果您需要快速检查令牌有效负载，请在本地解码访问令牌或将其粘贴到您组织批准的JWT检查工具中。

4.验证端点可达性和角色假设

此步骤假设Snowflake外部OAuth集成已经存在，并且与您之前验证的受众和发行者值匹配。

TOKEN=$(az account get-access-token --resource "api://" --query accessToken -o tsv)
ROLE=""

curl -s -X POST "https://.snowflakecomputing.com/api/v2/databases//schemas//mcp-servers/" \
	-H "Authorization: Bearer $TOKEN" \
	-H "X-Snowflake-Authorization-Token-Type: OAUTH" \
	-H "X-Snowflake-Role: $ROLE" \
	-H "Content-Type: application/json" \
	-d '{
		"jsonrpc": "2.0",
		"id": 2,
		"method": "tools/call",
		"params": {
			"name": "sql-exec-tool",
			"arguments": {
				"sql": "SELECT CURRENT_USER() AS user, CURRENT_ROLE() AS role"
			}
		}
	}'

这不仅验证了原始可达性。它验证令牌获取是否有效，端点是否正确，用户是否已映射，以及所选角色是否可以实际担任。

如果简单，Windows用户可以使用PowerShell或WSL运行相同的请求 curl 不方便。

扩展设置

配置示例：

{
	"snowflakeMcp.endpointUrl": "https://.snowflakecomputing.com/api/v2/databases/MCP_DB/schemas/MCP_SCHEMA/mcp-servers/SQL_EXEC_SERVER",
	"snowflakeMcp.azureAppIdUri": "api://",
	"snowflakeMcp.azureTenantId": "",
	"snowflakeMcp.role": "SYSADMIN",
	"snowflakeMcp.serverLabel": "snowflakeMcpAzAuth",
	"snowflakeMcp.useAzureCli": true
}

开发的等效当地值如所示 .env.示例.

命令面板命令

• Snowflake MCP: Refresh Azure Token
• Snowflake MCP: Test Connection
• Snowflake MCP: Show Effective Configuration

故障排除

az account get-access-token 失败

通常其中一个是错误的：

• 错误的租户
• 缺失或受限同意
• Azure CLI未在应用程序注册上预先授权
• 应用程序ID URI错误

第一次重试：

az login --scope "api:///session:role-any" --allow-no-subscriptions

雪花归来 404

您的端点错误。用途：

/api/v2/databases//schemas//mcp-servers/

不追加 /mcp.

Snowflake返回身份验证或角色错误

检查所有这些：

• aud 火柴 EXTERNAL_OAUTH_AUDIENCE_LIST
• iss 火柴 EXTERNAL_OAUTH_ISSUER
• 映射的声明与Snowflake用户匹配
• 用户可以担任发送的角色 X-Snowflake-Role
• 该角色在数据库、架构和MCP服务器上有使用

访客或外部用户意外失败

验证令牌是否确实包含 email 声明，它与Snowflake用户的完全匹配 EMAIL 属性。

扩展报告配置问题

跑 Snowflake MCP: Show Effective Configuration.

当前版本要求：

• 有效的端点URL
• 非空 snowflakeMcp.azureAppIdUri
• snowflakeMcp.useAzureCli = true

发展

npm install
npm run check
npm run build
npm test

要在本地创建VSIX，请执行以下操作：

npm run package:vsix

当前限制

运行时身份验证仍然依赖于Azure CLI。

扩展管理登录尚未实现。

参考文献

• 上游雪花MCP设置：
• 支持和问题：