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客戶端將根據用戶的提示確定使用哪個（哪些）實例。