Azure AI Search MCP Server

A custom Model Context Protocol (MCP) server for exposing Azure AI Search retrieval capabilities to MCP-compatible clients.

This server provides one customer-friendly tool layer for keyword search, semantic search, vector search, hybrid search, semantic hybrid search, and Azure AI Search Knowledge Base retrieval.

When To Use This

Use this project when you want one MCP server that exposes multiple Azure AI Search retrieval modes behind a small, stable set of tools.

Azure AI Search Knowledge Bases also expose a native MCP endpoint for direct Knowledge Base retrieval:

https://<your-service-name>.search.windows.net/knowledgebases/<your-knowledge-base-name>/mcp?api-version=<api-version>

This native endpoint is available for Knowledge Base objects, not ordinary search indexes. Microsoft documents it in Query a knowledge base using the retrieve action or MCP endpoint.

If your client only needs Knowledge Base retrieval, the native endpoint can be enough. This project is useful when you also want direct access to traditional search modes such as keyword, semantic, vector, hybrid, and semantic hybrid retrieval.

Features

• Keyword search with filters, selected fields, and search field scoping.
• Semantic search with semantic ranking, captions, and answers.
• Vector search using integrated vectorization from an index vectorizer.
• Hybrid search combining keyword and vector retrieval.
• Semantic hybrid search with hybrid retrieval plus semantic reranking.
• Knowledge Base retrieval through the Azure AI Search Python SDK preview client.
• Focused tool parameters for common use, with low-frequency SDK tuning under advanced_options.

Tools

Tool	Use when
simple_search	You need standard keyword or BM25 search.
semantic_search	You need semantic ranking, captions, or answers from a semantic configuration.
vector_search	You need vector-only similarity search using integrated vectorization.
hybrid_search	You need keyword and vector retrieval in one query.
semantic_hybrid_search	You need hybrid retrieval plus semantic reranking, captions, or answers.
agentic_retrieval	You need Azure AI Search Knowledge Base / Agentic Retrieval.

Quick Start

Docker

1）Generate a strong random token (optional, used as MCP_BEARER_TOKEN)

openssl rand -hex 32

2）Start the container with MCP_BEARER_TOKEN configured

docker run -itd -p 8000:8000 --name AzureAISearch \
  --restart unless-stopped \
  -e AZURE_AI_SEARCH_ENDPOINT=https://your-search-service.search.windows.net \
  -e AZURE_AI_SEARCH_QUERY_KEY=your-query-key \
  -e AZURE_AI_SEARCH_ADMIN_KEY=your-admin-key \
  -e MCP_BEARER_TOKEN=your-strong-random-token \
  -e MCP_HOST=0.0.0.0 \
  -e MCP_PORT=8000 \
  ghcr.io/heyjiqingcode/azureaisearchmcp:1.0.0

See Configuration for every available variable.

3）Configure your MCP client (http)

{
  "mcpServers": {
    "AzureAISearch": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp",
      "headers": {
        "Authorization": "Bearer your-strong-random-token"
      }
    }
  }
}

Omit the headers block if MCP_BEARER_TOKEN is not set on the server.
The type value depends on your MCP client: Claude Code and VS Code use "http", while some clients (e.g. Cherry Studio, Cline) call it "streamableHttp". Both mean Streamable HTTP.

Local

1）Set up

# Clone code and install requirements
git clone https://github.com/HeyJiqingCode/AzureAISearchMCP.git
cd AzureAISearchMCP
pip install -r requirements.txt

# Copy .env.example and fill in your Azure AI Search settings
cp .env.example .env

2）Run the server from source

# stdio — normally launched by your MCP client instead (see step 3)
python src/mcp/server.py --transport stdio

# http — HTTP on port 8000
python src/mcp/server.py --transport http

With stdio, environment variables are read from the project-root .env file. You can also pass them through the client's env field instead.
MCP_BEARER_TOKEN is optional for local runs: stdio never uses auth. For http, set it (or bind MCP_HOST=127.0.0.1) if other machines can reach the port.
See Configuration for every available variable.

3）Configure your MCP client (stdio)

{
  "mcpServers": {
    "AzureAISearch": {
      "type": "stdio",
      "command": "python",
      "args": ["/path/to/AzureAISearchMCP/src/mcp/server.py"]
    }
  }
}

Configuration

Environment Variables

Setting	Required	Used by	Description
AZURE_AI_SEARCH_ENDPOINT	Yes	All tools	Azure AI Search service endpoint.
AZURE_AI_SEARCH_QUERY_KEY	Yes	Search tools	Query key for keyword, semantic, vector, hybrid, and semantic hybrid tools.
AZURE_AI_SEARCH_ADMIN_KEY	For Agentic	agentic_retrieval	Admin key used by Knowledge Base retrieval. Treat it as sensitive.
MCP_BEARER_TOKEN	Recommended for HTTP	HTTP transport	Bearer token required by the HTTP transport. When unset, the endpoint accepts unauthenticated requests. stdio never requires auth.
MCP_HOST	No	HTTP transport	Host used by the http transport. Default: 0.0.0.0.
MCP_PORT	No	HTTP transport	Port used by the http transport. Default: 8000.
AZURE_AI_SEARCH_TIMEOUT	No	Search tools	How long this MCP server waits for standard search calls. Default: 30.
AZURE_AI_SEARCH_AGENTIC_TIMEOUT	No	agentic_retrieval	How long this MCP server waits for Agentic Retrieval calls. Default: 90.
AZURE_AI_SEARCH_AGENTIC_TIMEOUT_BUFFER	No	agentic_retrieval	Extra wait time added when max_runtime_seconds is set. Default: 30.

Timeout Settings

Standard search tools use AZURE_AI_SEARCH_TIMEOUT.

Agentic Retrieval uses two timeout layers:

• max_runtime_seconds: a tool argument that asks Azure AI Search to stop the Knowledge Base retrieve operation after that many seconds.
• AZURE_AI_SEARCH_AGENTIC_TIMEOUT: how long this MCP server is willing to wait for Azure AI Search to respond.
• AZURE_AI_SEARCH_AGENTIC_TIMEOUT_BUFFER: extra waiting time added when max_runtime_seconds is set.

Example: if max_runtime_seconds=60 and AZURE_AI_SEARCH_AGENTIC_TIMEOUT_BUFFER=30, this MCP server waits up to 90 seconds. This gives Azure AI Search 60 seconds to run, plus 30 seconds for network and response overhead.

Tool Reference

simple_search

Keyword search over an index using simple query syntax.

simple_search(index_name, query, top=5, skip=0, search_fields="", select="", filter="", search_mode="any", advanced_options="")

{
  "tool": "simple_search",
  "arguments": {
    "index_name": "knowledge-base",
    "query": "How to configure Wi-Fi for Windows PC?",
    "top": 3,
    "select": "title,body"
  }
}

semantic_search

Semantic reranked search for indexes with semantic configuration enabled.

semantic_search(index_name, query, semantic_configuration, top=5, skip=0, select="", filter="", query_caption="extractive", query_caption_highlight_enabled=True, query_answer="", advanced_options="")

{
  "tool": "semantic_search",
  "arguments": {
    "index_name": "knowledge-base",
    "query": "How to configure Wi-Fi for Windows PC?",
    "semantic_configuration": "default",
    "top": 3
  }
}

vector_search

Vector-only similarity search using integrated vectorization.

vector_search(index_name, vector_fields, vector_text, k=10, select="", filter="", advanced_options="")

{
  "tool": "vector_search",
  "arguments": {
    "index_name": "knowledge-base",
    "vector_fields": "text_vector",
    "vector_text": "How to configure Wi-Fi for Windows PC?",
    "k": 5,
    "select": "title,summary"
  }
}

hybrid_search

Hybrid keyword and vector search using Reciprocal Rank Fusion.

hybrid_search(index_name, query, vector_fields, vector_text, k=10, top=10, select="", filter="", search_fields="", advanced_options="")

{
  "tool": "hybrid_search",
  "arguments": {
    "index_name": "knowledge-base",
    "query": "How to configure Wi-Fi for Windows PC?",
    "vector_fields": "text_vector",
    "vector_text": "How to configure Wi-Fi for Windows PC?",
    "k": 20,
    "top": 5,
    "search_fields": "title,body"
  }
}

semantic_hybrid_search

Hybrid retrieval with semantic reranking, captions, and answers.

semantic_hybrid_search(index_name, query, vector_fields, semantic_configuration, vector_text, k=50, top=10, select="", filter="", search_fields="", query_caption="extractive", query_caption_highlight_enabled=True, query_answer="", advanced_options="")

{
  "tool": "semantic_hybrid_search",
  "arguments": {
    "index_name": "knowledge-base",
    "query": "How to configure Wi-Fi for Windows PC?",
    "vector_fields": "text_vector",
    "semantic_configuration": "default",
    "vector_text": "How to configure Wi-Fi for Windows PC?",
    "k": 30,
    "top": 5,
    "query_caption": "extractive",
    "query_answer": "extractive"
  }
}

advanced_options

advanced_options is a JSON object string for less common SDK tuning settings. Unsupported keys are rejected.

Common keys:

debug

Semantic keys:

semantic_query, query_answer_count, query_answer_threshold, semantic_error_mode, semantic_max_wait_in_milliseconds

Vector keys:

exhaustive, weight, oversampling, filter_override, vector_filter_mode, vector_similarity_threshold, search_score_threshold

Hybrid keys:

max_text_recall_size, count_and_facet_mode

Example:

{
  "advanced_options": "{\"max_text_recall_size\":100,\"vector_filter_mode\":\"preFilter\"}"
}

Agentic Retrieval

agentic_retrieval runs Azure AI Search Knowledge Base retrieval through the Python SDK preview client.

agentic_retrieval(knowledge_base_name, query, intent_query="", reasoning_effort="low", output_mode="answerSynthesis", include_activity=True, max_runtime_seconds=0, max_output_size=0, max_output_documents=0, knowledge_source_configs="", query_source_authorization="", include_diagnostics=False)

Frequently used arguments:

Argument	Description
knowledge_base_name	Azure AI Search Knowledge Base name.
query	User question or retrieval query.
reasoning_effort	minimal, low, or medium. Default: low.
output_mode	answerSynthesis or extractedData. Default: answerSynthesis.
include_activity	Include query planning and retrieval activity details.
max_runtime_seconds	Ask Azure AI Search to cap service-side retrieval runtime.
max_output_size	Bound the grounded response payload size.
max_output_documents	Cap final grounding document count.
knowledge_source_configs	JSON object or JSON array string for runtime knowledge source settings.
query_source_authorization	End-user token for query-time permission enforcement.
include_diagnostics	Include normalized request details and timeout budget for troubleshooting. Default: false.

answerSynthesis requires message-based retrieval, so use reasoning_effort="low" or reasoning_effort="medium". Use reasoning_effort="minimal" with output_mode="extractedData" for direct semantic intent retrieval.

Response is structured for agent consumption:

• answer: object containing text and used_ref_ids. The answer text keeps Azure AI Search citation markers such as [ref_id:0]; used_ref_ids lists the cited reference IDs without the ref_id: prefix.
• references: normalized evidence objects referenced by answer.text, with fields such as ref_id, source_type, title, url, content, document_id, chunk_id, doc_key, knowledge_source_name, activity_source, and reranker_score.
• metadata: request and retrieval metadata such as knowledge_base_name, output_mode, reasoning_effort, elapsed_ms, referenced_count, and total_reference_count.
• diagnostics: included only when include_diagnostics=true; contains the normalized SDK request, timeout budget, raw response, raw references, and activity details.

To receive source chunks in references[].content, set includeReferenceSourceData=true in the relevant knowledge_source_configs entry. Azure AI Search only returns sourceData when the knowledge source is configured to include it.

Basic Example

{
  "tool": "agentic_retrieval",
  "arguments": {
    "knowledge_base_name": "kb-support",
    "query": "How do I reset my VPN password?",
    "reasoning_effort": "low",
    "output_mode": "answerSynthesis",
    "include_activity": true
  }
}

Minimal Intent Example

{
  "tool": "agentic_retrieval",
  "arguments": {
    "knowledge_base_name": "kb-support",
    "query": "How do I reset my VPN password?",
    "reasoning_effort": "minimal",
    "output_mode": "extractedData"
  }
}

Knowledge Source Configuration

Use knowledge_source_configs to specify one or more knowledge sources with per-source settings. Pass a JSON object or JSON array encoded as a string.

Common knowledge source config keys:

Key	Type	Description
knowledgeSourceName	string	Knowledge source name.
kind	string	Source type, such as searchIndex, web, azureBlob, indexedOneLake, or another preview kind supported by the SDK.
includeReferences	bool	Include document references.
includeReferenceSourceData	bool	Include source data in references.
rerankerThreshold	float	Minimum reranker score threshold.
alwaysQuerySource	bool	Force querying when supported by the selected source kind.
failOnError	bool	Treat this source as required.
maxOutputDocuments	int	Cap candidate documents from this source.
filterAddOn	string	Runtime OData filter for search index knowledge sources.
count, freshness, language, market	mixed	Web source controls.
filterExpressionAddOn	string	KQL filter expression for SharePoint-style sources.

Single source:

{
  "tool": "agentic_retrieval",
  "arguments": {
    "knowledge_base_name": "kb-support",
    "query": "How do I reset my VPN password?",
    "knowledge_source_configs": "{\"knowledgeSourceName\":\"ks-docs\",\"kind\":\"searchIndex\",\"includeReferences\":true,\"includeReferenceSourceData\":true}"
  }
}

Multiple sources:

{
  "tool": "agentic_retrieval",
  "arguments": {
    "knowledge_base_name": "kb-support",
    "query": "Latest security updates",
    "knowledge_source_configs": "[{\"knowledgeSourceName\":\"ks-docs\",\"kind\":\"searchIndex\",\"includeReferences\":true,\"includeReferenceSourceData\":true},{\"knowledgeSourceName\":\"ks-web\",\"kind\":\"web\",\"includeReferences\":true,\"count\":10,\"freshness\":\"week\"}]"
  }
}

Search field selection is handled by Azure AI Search based on Knowledge Base and index configuration.