Name: Azure AI Search MCP Server
Author: farzad528

LABSCO SUMMARY

One index, three ways to search it — or an agent that adds the open web.

Choosing between the two servers is choosing between reach and setup: direct to Azure AI Search is one endpoint, one key and three query modes, while the Agent Service route wants a project with search and Bing connections wired first and pays that back with cited public sources next to your own documents. If your index is not vectorised yet, start with keyword search — it is the only mode that will return anything useful.

What it is

Two Python servers in one repository, and you pick one. The direct server talks straight to Azure AI Search and offers three retrieval modes over your index: keyword for exact lexical matches, vector for semantic similarity over embeddings, and hybrid for both in a single call, each returning the top results formatted as markdown. The Agent Service server goes through Azure AI Agent Service instead, which puts the same index behind an agent and adds Bing web grounding, so an answer can carry citations to public sources alongside your own documents.

What you get

Keyword search over your index — exact lexical matching, returning as many results as you ask for
Vector search over the same index, matching on embedding similarity rather than wording
Hybrid search combining lexical and vector matching in one call
Document search through Azure AI Agent Service, with the agent's own processing applied to the results
Bing web search through that same agent, returning citations to the original sources
Results rendered as markdown rather than raw response payloads

Requirements

Python 3.10 or newer and an Azure AI Search service whose index already contains vectorised text — the vector and hybrid modes have nothing to match on otherwise. The direct server takes the search endpoint, the index name and an API key. The Agent Service path asks for more: an Azure AI Project with connections to AI Search and to Bing, a model deployment name, and an az login for the identity behind them. Either script is launched by absolute path from the virtual environment you install into.

Setup effort

Build from source — git clone https://github.com/farzad528/mcp-server-azure-ai-agents.git

See installation options

USE CASES

01

Answering from your own documents

Search the index for the exact terms the question uses, and fall back to hybrid when the wording in the documents differs from the wording in the question.

02

Finding a passage you can only describe

Match on meaning rather than words, for the cases where the reader knows what the document says but not what it calls it.

03

Backing an internal answer with public sources

Search the index through the agent and run a web search alongside it, so the answer carries citations as well as internal evidence.

04

Deciding which retrieval mode your index needs

Run the same question through keyword, vector and hybrid and compare what each returns before wiring one into an application.

BEFORE YOU INSTALL

What to know first

Requires

Python 3.10 or newer

Optional

PROJECT_CONNECTION_STRING in your environment
MODEL_DEPLOYMENT_NAME in your environment
AI_SEARCH_CONNECTION_NAME in your environment
BING_CONNECTION_NAME in your environment
AI_SEARCH_INDEX_NAME in your environment
AZURE_SEARCH_SERVICE_ENDPOINT in your environment
AZURE_SEARCH_INDEX_NAME in your environment
AZURE_SEARCH_API_KEY in your environment

INSTALLATION

Connect your client

Server setup

TERMINAL

git clone https://github.com/farzad528/mcp-server-azure-ai-agents.git
cd mcp-server-azure-ai-agents
uv venv
uv pip install "mcp[cli]" azure-identity python-dotenv azure-ai-projects==1.0.0b7
az login

MCP Clients

Claude Desktop — Agent Service

CLAUDE DESKTOP — AGENT SERVICE · JSON

{
  "mcpServers": {
    "azure-ai-agent": {
      "command": "<YOUR_PATH_TO_VENV>\\Scripts\\python.exe",
      "args": [
        "<YOUR_PATH_TO_AZURE_AI_AGENT_SERVICE>"
      ],
      "env": {
        "PROJECT_CONNECTION_STRING": "<YOUR_PROJECT_CONNECTION_STRING>",
        "MODEL_DEPLOYMENT_NAME": "<YOUR_MODEL_DEPLOYMENT_NAME>",
        "AI_SEARCH_CONNECTION_NAME": "<YOUR_AI_SEARCH_CONNECTION_NAME>",
        "BING_CONNECTION_NAME": "<YOUR_BING_CONNECTION_NAME>",
        "AI_SEARCH_INDEX_NAME": "<YOUR_INDEX_NAME>"
      }
    }
  }
}

Azure AI Agent Service server. Run az login first. <YOUR_PATH_TO_VENV> and <YOUR_PATH_TO_AZURE_AI_AGENT_SERVICE> are the .venv and azure_ai_agent_service_server.py in your clone; the other values (connection string, model deployment name, Azure AI Search and Bing connection names) come from your Azure AI Project.

Pick one server: the Agent Service block needs the five project and connection values; the direct Azure AI Search block needs the search endpoint, index name and API key. Each block sets its own values in env.

Claude Desktop — Direct Search

CLAUDE DESKTOP — DIRECT SEARCH · JSON

{
  "mcpServers": {
    "azure-search": {
      "command": "<YOUR_PATH_TO_VENV>\\Scripts\\python.exe",
      "args": [
        "<YOUR_PATH_TO_AZURE_SEARCH_SERVER>"
      ],
      "env": {
        "AZURE_SEARCH_SERVICE_ENDPOINT": "https://<YOUR_SERVICE_NAME>.search.windows.net",
        "AZURE_SEARCH_INDEX_NAME": "<YOUR_INDEX_NAME>",
        "AZURE_SEARCH_API_KEY": "<YOUR_AZURE_SEARCH_API_KEY>"
      }
    }
  }
}

Direct Azure AI Search server, the alternative to the Agent Service one. It needs different packages: uv pip install "mcp[cli]" azure-search-documents==11.5.2 azure-identity python-dotenv. <YOUR_PATH_TO_VENV> and <YOUR_PATH_TO_AZURE_SEARCH_SERVER> are your clone's .venv and azure_search_server.py, and <YOUR_AZURE_SEARCH_API_KEY> is the admin key.