Experimental MCP Service for Azure AI Search

Azure AI Search 向け実験的 MCP サービス

この実験的な MCP サービスでは、次の機能を利用できます。

• サービスから AI Search インデックスの一覧を取得する
• 特定の AI Search サービスのスキーマと構成の詳細を取得する
• 新しいインデックスを作成する
• 既存のインデックスを更新する
• 特定の AI Search インデックスに対してクエリを実行する
• インデクサーを作成および更新する

プロジェクトの移転

このプロジェクトは当初ここで公開されていましたが、チームが次の公式の場所に移転しました。 https://github.com/azure-ai-foundry/mcp-foundry

重要な免責事項

これらの機能は現在も実装およびテスト中です。

上記のツールグループの一部はまだ利用できませんが、近日中に利用可能になる予定です。

サービス機能の追加と強化に継続的に取り組んでいます。近い将来、さらに多くのツールが追加される予定です。

これらのツールを使用すると、AI Search サービス内のデータを変更できます。

すべてのツールは現在 experimental としてマークされており、without advanced notice に動作が変更される場合がありますのでご注意ください。

AI が生成したコンテンツは、正確性と妥当性を必ず確認してください。

十分にご注意のうえ、自己責任でご利用ください。

利用可能なツール

現時点では、サービスから以下のツールを利用できます。

ツール名	ツールグループ	ツールの説明
list_index_names	READ_INDEX	AI Search Service のすべてのインデックス名を取得します
list_index_schemas	READ_INDEX	AI Search Service のすべてのインデックススキーマを取得します
retrieve_index_schema	READ_INDEX	特定のインデックスのスキーマを取得します
create_index	WRITE_INDEX	新しいインデックスを作成します
modify_index	WRITE_INDEX	既存のインデックスの定義を変更します
delete_index	WRITE_INDEX	既存のインデックスを削除します
add_document	WRITE_DOCUMENTS	インデックスにドキュメントを追加します
delete_document	WRITE_DOCUMENTS	インデックスからドキュメントを削除します
query_index	READ_DOCUMENTS	特定のインデックスを検索し、一致するドキュメントを取得します
get_document_count	READ_DOCUMENTS	インデックス内のドキュメントの合計数を返します
list_indexers	READ_INDEXER	AI Search Service のすべてのインデクサー名を取得します
get_indexer	READ_INDEXER	AI Search Service の特定のインデクサーの完全な定義を取得します
create_indexer	WRITE_INDEXER	スキル、インデックス、データソースを指定して、Search Service に新しいインデクサーを作成します
delete_indexer	WRITE_INDEXER	名前を指定して、AI Search Service のインデクサーを削除します
list_data_sources	READ_INDEXER	AI Search Service のすべてのデータソース名を取得します
get_data_source	READ_INDEXER	特定のデータソースの完全な定義を取得します
list_skill_sets	READ_INDEXER	AI Search Service のすべてのスキルセット名を取得します
get_skill_set	READ_INDEXER	特定のスキルセットの完全な定義を取得します
fk_fetch_local_file_contents	FETCH_FILE_CONTENTS	ローカルファイルのパス（サンプル JSON、ドキュメントなど）の内容を取得します
fk_fetch_url_contents	FETCH_FILE_CONTENTS	URL（サンプル JSON、ドキュメントなど）の内容を取得します

MCP サービスのツールグループ

このサービスから提供される大量のツールで、MCP ホストに負荷がかかることは避けたいと考えています。

利用可能なツールグループとその用途は次のとおりです。

• READ_OPERATIONS - 読み取り専用操作に使用するツール
• WRITE_OPERATIONS - エントリの作成、変更、削除に使用するツール。ALL のエイリアスです
• READ_INDEX - サービス内のインデックスを一覧表示して説明するためのツール
• WRITE_INDEX - インデックスの作成、削除、更新、構成に使用するツール
• READ_DOCUMENTS - インデックスをクエリしてドキュメントを取得するためのツール
• WRITE_DOCUMENTS - インデックス内のドキュメントの追加、更新、削除に使用するツール
• WRITE_INDEXERS - インデクサー、データソース、スキルセットの構成に使用するツール
• READ_INDEXERS - データソース、スキルセット、インデクサーに関する情報を取得するためのツール

前提条件

利用する AI Search サービスへの認証に使用するサービスプリンシパルを構成する必要があります。また、サービスのどの機能を利用するかに応じて、インデックスに対する読み取り／書き込み権限を持つ AI Search キーを使用することもできます。

Python 3.12 以降が必要です。また、このサービスを利用するには uv もインストールする必要があります。

以下のリポジトリには、AI Search サービスと、利用開始に必要なサービスプリンシパルのプロビジョニングを迅速化する Terraform スクリプトが含まれています。

依存関係のインストール

uv、Python、MCP サービスを含むモジュールのインストールには、以下のリンクを参照してください。

• uv のインストール
• 必要に応じて uv を使用して Python をインストール

MCP サービスは、次のようにインストールできます。

uv build

pip install dist/mcp_server_azure_ai_search_preview-0.3.1-py3-none-any.whl 

# If you are running in SSE mode, you can run it as:
uv run -m mcp_server_azure_ai_search_preview --transport sse --envFile .env --host 127.0.0.1 --port 8000

#f you are running it in STDIO mode in Cursor or Claude Desktop, we have an example config below for you to use

環境ファイル、ホスト、ポートの指定は任意です。指定しない場合は、デフォルト値が使用されます。

この Git リポジトリをクローンし、リポジトリ内の main.py ファイルからサービスをインストールすることもできます。

MCP ホストの環境変数の設定

マネージド ID で認証する場合は、MCP ホストの設定に環境変数を渡す必要があります。AI Search API キーを使って認証することもできます。

認証方法と検索エンドポイントを指定する必要があります。以下は必須の環境変数です。

サービスプリンシパルで認証する場合は、次の変数を設定してください。

• AZURE_AUTHENTICATION_METHOD - デフォルトは "api-search-key" です
• AZURE_AI_SEARCH_ENDPOINT
• AZURE_TENANT_ID
• AZURE_CLIENT_ID
• AZURE_CLIENT_SECRET

API キーで認証する場合は、次の環境変数を設定してください。

• AZURE_AUTHENTICATION_METHOD - デフォルトは "api-search-key" です
• AZURE_AI_SEARCH_ENDPOINT
• AZURE_AUTHENTICATION_METHOD
• AZURE_AI_SEARCH_API_KEY

設定でツールグループをカンマ区切りのリストとして指定することで、MCP ホストに返されるツールの一覧をフィルターすることもできます。

環境変数	値のデータ型	必要な理由
AZURE_AUTHENTICATION_METHOD	string	サービスプリンシパルベースのアクセスには "service-principal"、キーによるアクセスには "api-search-key" を指定します。
AZURE_AI_SEARCH_ENDPOINT	string (URL)	Azure AI Search のエンドポイント URL を指定します。サービスへの REST API リクエストの送信に使用されます。
AZURE_TENANT_ID	string	サービスプリンシパルによる認証に使用する Azure Active Directory（AAD）テナントを識別します。
AZURE_CLIENT_ID	string	Azure 認証に使用するサービスプリンシパル（アプリ登録）の一意の識別子です。
AZURE_CLIENT_SECRET	string	サービスプリンシパルのシークレット認証情報です。AAD から認証してトークンを取得するために使用されます。
AZURE_AI_SEARCH_API_KEY	string	Azure AI Search インスタンスへの読み取り／書き込み API リクエストの認証に使用します。安全に保管してください。
AZURE_AI_SEARCH_API_VERSION	string	使用する API バージョンです。
AZURE_AI_SEARCH_MCP_TOOL_GROUPS	string	MCP ホスト向けにツールを取得する際にフィルターするツールグループのカンマ区切りリストです。

STDIO モードでの MCP ホストの設定

STDIO トランスポートを使用する VScode Agent Mode の MCP 設定例です。

{
    "inputs": [
        {
            "type": "promptString",
            "id": "AZURE_AI_SEARCH_API_KEY",
            "description": "AZURE_AI_SEARCH_API_KEY",
            "password": true
        },
        {
            "type": "promptString",
            "id": "LOCAL_WORKING_DIRECTORY",
            "description": "Directory where the MCP service Git repo was cloned to",
            "password": false
        }
    ],
    "servers": {

        "ai_search_mcp": {
            "type": "stdio",
            "command": "uv",

            "args": [
                "run",
                "--directory",
                "${input:LOCAL_WORKING_DIRECTORY}",
                "-m",
                "run mcp_server_azure_ai_search_preview"
                "--transport",
                "stdio"
            ],
            "env": {
                "AZURE_AI_SEARCH_MCP_TOOL_GROUPS": "ALL",
                "AZURE_AI_SEARCH_ENDPOINT": "https://{service_name}.search.windows.net",
                "AZURE_AI_SEARCH_API_VERSION": "2025-03-01-preview",
                "AZURE_AUTHENTICATION_METHOD": "api-search-key",
                "AZURE_AI_SEARCH_API_KEY":  "${input:AZURE_AI_SEARCH_API_KEY}"
            }
        }
    }
}

この例では、MCP サーバーが使用する環境変数を指定するために、カスタム環境変数ファイルを使用します。

{
    "inputs": [
        {
            "type": "promptString",
            "id": "LOCAL_WORKING_DIRECTORY",
            "description": "Directory where the MCP service Git repo was cloned to",
            "password": false
        }
    ],
    "servers": {

        "ai_search_mcp": {
            "type": "stdio",
            "command": "uv",
            "args": [
                "run",
                "--directory",
                "${input:LOCAL_WORKING_DIRECTORY}",
                "-m",
                "run mcp_server_azure_ai_search_preview"
                "--transport",
                "stdio"
               "--envFile",
                ".env"
            ]
        }
    }
}

この例では、SSE モードで実行される MCP サーバーを使用します。

# Start up the MCP server first and then specify this config in your `.vscode/mcp.json` file in your VSCODE workspace

uv run -m mcp_server_azure_ai_search_preview --transport sse --envFile .env

{
    "servers": {
        "ai_search_2": {
            "type": "sse",
            "url": "http://localhost:8000/sse"
        }
    }
}

Pydantic AI などのエージェントフレームワークから実行する

Pydantic AI のような Python エージェントフレームワークを使って MCP クライアントを実行する方法については、このリポジトリの例を参照してください。

Python MCP クライアントを起動する前に、クライアントコードが依存するすべての SSE MCP サーバーが起動していることを確認してください。