Snowflake Cortex MCP Server - NodeJS

Snowflake Cortex AI Model Context Protocol（MCP）サーバー

この Snowflake MCP サーバーは、Snowflake Cortex AI の機能を利用するためのツールを提供し、これらの機能を MCP エコシステムに取り入れます。MCP クライアント（Claude for Desktop、fast-agent、Agentic Orchestration Framework など）に接続すると、ユーザーはこれらの Cortex AI 機能を活用できます。

現在、MCP サーバーは以下の Cortex AI 機能をサポートしています。

• Cortex Search：Retrieval Augmented Generation（RAG）アプリケーションで一般的に使用される、Snowflake 内の非構造化データのクエリです。
• Cortex Analyst：豊富なセマンティックモデリングを通じて、Snowflake 内の構造化データにクエリを実行します。
• Cortex Agent：構造化データと非構造化データの取得を横断するエージェント型オーケストレーターです。

実行：

yarn dev

MCP サーバーは Next.js API バックエンドと同じものではありません。

• MCP サーバー

  - Runs as a sidecar/service.
  - Communicates with an MCP client (like VS Code, Cursor, Claude Desktop).
  - Protocol is `stdio`/`sockets`, not HTTP.
  - Tools are exposed via `server.tool("name", handler)`.
  - Goal: provide AI clients with structured capabilities (SQL exec, search, etc).

• Next.js API ルート

  - Exposes HTTP endpoints (`/api/runAgent`).
  - Clients are browsers, Postman, other web services.
  - Protocol is HTTP/JSON.
  - Goal: power web apps, user-facing dashboards, external integrations.

So putting MCP directly inside Next.js **doesn’t make sense** (MCP clients won’t connect to a Next.js API route).

Getting Started

Connecting to Snowflake

The MCP server uses the Snowflake Cortex / REST API for all authentication and connection methods. Please refer to the official Snowflake documentation for comprehensive authentication options and best practices.

Connection parameters can be passed as environment variables. The server supports Programmtic Access Token to make all API calls.

Payload Builder: Dynamically Creating Agent Requests

The MCP server provides a Payload Builder utility to dynamically construct requests for Cortex Agents. This eliminates hardcoding tool definitions, resources, or queries, making your integrations flexible and maintainable.

How It Works

[Your Query]  --->  buildAgentConfig()  --->  MCP Payload
                                 |
                                 v
                          [Tool Definitions]
                                 |
                                 v
                           [Tool Resources]
                                 |
                                 v
                        [Cortex Agent Server]
                                 |
                                 v
                    [Structured / Streamed Response]

• Query: The user’s natural language input.
• Tool Definitions: Each tool’s name, type, and optional resources.
• Tool Resources: Keyed by tool name (snake_case), includes semantic models, search indexes, etc.
• MCP Server: Consumes the payload and orchestrates the tools.
• Response: Streamed via SSE, parsed using processSSEResponse.

---

Example Usage

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";

// Build payload dynamically
const payload = buildAgentConfig(toolDefinitions, query);

// Run agent query
const result = await runCortexAgentQuery(payload, process.env.SNOWFLAKE_PAT);

console.error(result);

---

主なポイント

• 完全一致： tool_spec.name は tool_resources 内の snake_case キーと一致している必要があります。
• 環境変数： セマンティックビュー、検索サービスなどの動的な設定には .env を使用してください。
• ストリーミングレスポンス： MCP はストリーミングデータを返します。安全に解析するには、必ず processSSEResponse() を使用してください。
• ツールの拡張： toolDefinitions に新しいツールを追加すると、ビルダーがペイロードに自動的に含めます。

---

このセクションでは、開発者がプログラムでペイロードを生成する方法をすばやく理解し、tool_resources の不一致などのよくあるエラーを回避できるようにします。

MCP クライアントでの使用

この MCP サーバーは特定のクライアントに依存せず、MCP ツールの基本機能と（任意で）リソースをサポートするほとんどの MCP クライアントで動作します。以下に例を示します。

Claude Desktop

このサーバーを MCP クライアントとして Claude Desktop に統合するには、アプリのサーバー設定に以下を追加してください。デフォルトでは、次の場所にあります。

• 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 サーバーをコンテキストとして追加してください。

Microsoft Visual Studio Code + GitHub Copilot

前提条件、環境設定、手順ごとのガイドおよび説明については、このブログを参照してください。

トラブルシューティング

MCP Inspector の実行

MCP サーバーのトラブルシューティングには、MCP Inspector の使用をおすすめします。Inspector を起動するには、以下を実行してください。

`yarn inspector`

OR

`npx @modelcontextprotocol/inspector tsx --env-file .env dist/mcp/MCP.js`

詳細：INSPECTOR.md

よくある質問

Snowflake に接続するにはどうすればよいですか？

• Programmatic Access Token（PAT）を使用します。環境変数 SNOWFLAKE_PAT として設定してください。

どうすれば試せますか？

• MCP サーバーは、MCP エコシステムの一部として使用することを想定しています。ツールのコレクションとしてお考えください。オーケストレーターとして機能するMCP クライアントが必要です。詳しくは、MCP の概要をご覧ください。

これはどこにデプロイされますか？Snowpark Container Services 上ですか？

• このMCP サーバー内のすべてのツールはマネージドサービスであり、REST API 経由でアクセスできます。個別のリモートサービスをデプロイする必要はありません。代わりに、サーバーの現行バージョンは、Claude Desktop、Cursor、fast-agent などのMCP クライアントによって起動されることを想定しています。これらのMCP クライアントでサーバーを設定すると、アプリケーションがサーバーサービスを起動します。今後のバージョンでは、MCP サーバーがリモートサービスとしてデプロイされる可能性があります。

ツールの呼び出しで権限エラーが発生します。

• Programmatic Access Tokens を使用する場合、セカンダリロールは評価されないことにご注意ください。作成時に、すべてのサービスとその基盤となるオブジェクトにアクセスできる単一のロールを選択するか、任意のロールを選択してください。このプロパティを変更するには、新しいPATを作成する必要があります。

Cortex Search または Cortex Analysts はいくつ追加できますか？

• どちらのサービスも複数のインスタンスを追加できます。ユーザーのプロンプトに基づき、適切なインスタンスを判断するのはMCP クライアントです。