Snowflake Cortex MCP Server

🚀 Snowflake Cortex AIモデルコンテキストプロトコル (MCP) サーバー

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

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

• Cortex Search: 検索拡張生成 (RAG) アプリケーションで一般的に使用されるSnowflake内の非構造化データをクエリできます。
• Cortex Analyst: 豊富なセマンティックモデリングを介してSnowflake内の構造化データをクエリできます。
• Cortex Agent: 構造化および非構造化データの検索をまたがるエージェントオーケストレーターです。

実行方法:

yarn dev

MCPサーバーはNext.js APIバックエンドとは異なります。

• MCPサーバー

  - サイドカー/サービスとして実行されます。
  - MCPクライアント（VS Code、Cursor、Claude Desktopなど）と通信します。
  - プロトコルは`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ルートに接続しません）。

🚀 クイックスタート

🔗 Snowflakeへの接続

MCPサーバーは、すべての認証と接続方法に Snowflake Cortex / REST API を使用しています。包括的な認証オプションとベストプラクティスについては、Snowflakeの公式ドキュメントを参照してください。

接続パラメーターは環境変数として渡すことができます。サーバーはすべてのAPI呼び出しにプログラムアクセストークンをサポートしています。

🛠️ ペイロードビルダー: エージェントリクエストの動的作成

MCPサーバーは、Cortexエージェントのリクエストを動的に構築するためのペイロードビルダーユーティリティを提供しています。これにより、ツール定義、リソース、またはクエリをハードコーディングする必要がなくなり、統合が柔軟で保守しやすくなります。

動作原理

[あなたのクエリ]  --->  buildAgentConfig()  --->  MCPペイロード
                                 |
                                 v
                          [ツール定義]
                                 |
                                 v
                           [ツールリソース]
                                 |
                                 v
                        [Cortexエージェントサーバー]
                                 |
                                 v
                    [構造化/ストリーミングレスポンス]

• クエリ: ユーザーの自然言語入力です。
• ツール定義: 各ツールのname、type、およびオプションのresourcesです。
• ツールリソース: ツール名（スネークケース）でキー付けされ、セマンティックモデル、検索インデックスなどが含まれます。
• 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 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インスペクターの実行

MCPインスペクターは、MCPサーバーのトラブルシューティングに推奨されます。インスペクターを起動するには、以下を実行します。

`yarn inspector`

または

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

詳細: INSPECTOR.md

❓ よくある質問

Snowflakeにどのように接続しますか？

• プログラムアクセストークン (PAT) を使用します。環境変数SNOWFLAKE_PATとして設定してください。

これを試すにはどうすればいいですか？

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

これはどこにデプロイされますか？Snowparkコンテナサービスにありますか？

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

ツール呼び出しでパーミッションエラーが発生します。

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

いくつのCortex SearchまたはCortex Analystを追加できますか？

• 両方のサービスの複数のインスタンスを追加できます。MCPクライアントがユーザーのプロンプトに基づいて適切なインスタンスを決定します。