Snowflake Cortex MCP Server

🚀 雪花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客户端将根据用户的提示确定使用哪个（哪些）实例。