🚀 雪花Cortex AI模型上下文协议（MCP）服务器
雪花MCP服务器为雪花Cortex AI功能提供工具，将这些功能引入MCP生态系统。当连接到MCP客户端（如桌面版Claude、快速代理、代理编排框架）时，用户可以利用这些Cortex AI功能。
MCP服务器目前支持以下Cortex AI功能：
- Cortex搜索：查询雪花中的非结构化数据，常用于检索增强生成（RAG）应用程序。
- Cortex分析器：通过丰富的语义建模查询雪花中的结构化数据。
- Cortex代理：跨结构化和非结构化数据检索的代理编排器
运行：
yarn dev
📌 MCP服务器与Next.js API后端不同：
- MCP服务器
- 作为边车/服务运行。
- 与MCP客户端（如VS Code、Cursor、桌面版Claude）通信。
- 协议是`stdio`/`sockets`，而非HTTP。
- 工具通过`server.tool("name", handler)`暴露。
- 目标：为AI客户端提供结构化功能（SQL执行、搜索等）。
- Next.js API路由
- 暴露HTTP端点（`/api/runAgent`）。
- 客户端是浏览器、Postman和其他Web服务。
- 协议是HTTP/JSON。
- 目标：为Web应用程序、面向用户的仪表板和外部集成提供支持。
因此，将MCP直接放在Next.js中**没有意义**（MCP客户端不会连接到Next.js API路由）。
🚀 快速开始
连接到雪花
MCP服务器使用雪花Cortex / REST API进行所有身份验证和连接方法。请参考雪花官方文档以获取全面的身份验证选项和最佳实践。
连接参数可以作为环境变量传递。服务器支持使用编程访问令牌进行所有API调用。
有效负载构建器：动态创建代理请求
MCP服务器提供了一个有效负载构建器实用工具，用于为Cortex代理动态构建请求。这消除了对工具定义、资源或查询进行硬编码的需求，使您的集成更加灵活和易于维护。
工作原理
[您的查询] ---> buildAgentConfig() ---> MCP有效负载
|
v
[工具定义]
|
v
[工具资源]
|
v
[Cortex代理服务器]
|
v
[结构化/流式响应]
- 查询：用户的自然语言输入。
- 工具定义：每个工具的
名称、类型和可选的资源。 - 工具资源：按工具名称（蛇形命名法）键控，包括语义模型、搜索索引等。
- MCP服务器：使用有效负载并编排工具。
- 响应：通过SSE流式传输，使用
processSSEResponse进行解析。
示例用法
import { buildAgentConfig, ToolDefinition } from "./mcp/payloadBuilder";
import { runCortexAgentQuery } from "./mcp/MCP";
const toolDefinitions: ToolDefinition[] = [
{
name: "Text2SQL",
type: "cortex_analyst_text_to_sql",
resources: { semantic_model_file: process.env.SEMANTIC_MODEL_VIEW }
},
{
name: "Vehicles_Search",
type: "cortex_search",
resources: {
name: process.env.VEHICLES_SEARCH_SERVICE,
id_column: "relative_path",
title_column: "title",
max_results: 10
}
},
{ name: "sql_execution_tool", type: "sql_exec" }
];
const query = "Show me the top selling brands by total sales quantity in TX for Books in 2003";
// 动态构建有效负载
const payload = buildAgentConfig(toolDefinitions, query);
// 运行代理查询
const result = await runCortexAgentQuery(payload, process.env.SNOWFLAKE_PAT);
console.error(result);
关键点
- 精确匹配：
tool_spec.name必须与tool_resources中的蛇形命名法键匹配。 - 环境变量：使用
.env文件动态配置语义视图、搜索服务等。 - 流式响应：MCP返回流式数据；始终使用
processSSEResponse()安全地解析它。 - 扩展工具：将新工具添加到
toolDefinitions中，构建器会自动将它们包含在有效负载中。
这部分将帮助开发人员快速了解如何以编程方式生成有效负载，并避免诸如tool_resources不匹配等常见错误。
💻 与MCP客户端一起使用
MCP服务器与客户端无关，可与大多数支持MCP工具基本功能和（可选）资源的MCP客户端配合使用。以下是一些示例。
桌面版Claude
要将此服务器与桌面版Claude作为MCP客户端集成，请将以下内容添加到应用程序的服务器配置中。默认情况下，该配置文件位于：
- macOS：~/Library/Application Support/Claude/claude_desktop_config.json
- Windows：%APPDATA%\Claude\claude_desktop_config.json
设置服务配置文件的路径并配置连接方法。
{
"mcpServers": {
"Cortex Agent AI": {
"command": "ABSOLUTE_PATH\\npx.cmd",
"args": [
"tsx",
"--watch",
"--env-file",
"ABSOLUTE_PATH\\.env",
"ABSOLUTE_PATH\\src\\mcp\\MCP.ts"
]
}
}
}
在聊天中添加MCP服务器作为上下文。
微软Visual Studio Code + GitHub Copilot
有关先决条件、环境设置、分步指南和说明，请参考此博客。
🛠️ 故障排除
运行MCP检查器
建议使用MCP检查器来排查MCP服务器的问题。运行以下命令启动检查器：
`yarn inspector`
或者
`npx @modelcontextprotocol/inspector tsx --env-file .env dist/mcp/MCP.js`
阅读更多：INSPECTOR.md
❓ 常见问题解答
如何连接到雪花？
- 使用编程访问令牌（PAT）。将其设置为环境变量SNOWFLAKE_PAT。
如何试用此功能？
- MCP服务器旨在作为MCP生态系统的一部分使用。可以将其视为一组工具。您需要一个MCP客户端作为编排器。有关更多信息，请参阅MCP简介。
此服务器部署在哪里？是否在Snowpark容器服务中？
- 此MCP服务器中的所有工具都是托管服务，可通过REST API访问。无需单独部署远程服务。相反，当前版本的服务器旨在由MCP客户端（如桌面版Claude、Cursor、快速代理等）启动。通过使用服务器配置这些MCP客户端，应用程序将为您启动服务器服务。未来版本的MCP服务器可能会作为远程服务部署。
我在工具调用时收到权限错误。
- 如果使用编程访问令牌，请注意它们不会评估次要角色。创建令牌时，请选择一个可以访问所有服务及其基础对象的单一角色，或者选择任何角色。若要更改此属性，需要创建一个新的PAT。
我可以添加多少个Cortex搜索或Cortex分析器实例？
- 您可以添加多个这两种服务的实例。MCP客户端将根据用户的提示确定使用哪个（哪些）实例。