Azure AI Agent Service + Azure AI Search

This MCP server enables Claude Desktop to leverage Azure AI capabilities for searching your content. You can choose between using the Azure AI Agent Service with both document search and web search, or connect directly to Azure AI Search for flexible search options. The setup provides practical tools to quickly index, analyze, and retrieve information from your data and the web.

How to use

You use this MCP server by running one or more local MCP processes and pointing Claude Desktop to the running servers. The Agent Service option exposes an AI-enhanced document search and a Bing web grounding tool with citations. The Direct Azure AI Search option connects directly to your Azure AI Search index using keyword, vector, or hybrid search. Start the servers, configure Claude Desktop with the appropriate MCP server entries, and then issue queries from Claude Desktop to retrieve results from your private documents, the web, or both.

How to install

Prerequisites you need before starting: Python 3.10 or higher, Claude Desktop (latest version), and Azure resources (Azure AI Search with an index; optional Azure AI Project, and Bing for web search if you choose the Agent Service). You will run commands in a Windows or macOS environment, with Windows commands shown here as examples.

# Step 1: Create a working directory for the MCP server
mkdir mcp-server-azure-ai-search
cd mcp-server-azure-ai-search

# Step 2: Create a .env file with your project and connections
# This example uses placeholders you will replace with your actual values
echo "PROJECT_CONNECTION_STRING=your-project-connection-string" > .env
echo "MODEL_DEPLOYMENT_NAME=your-model-deployment-name" >> .env
echo "AI_SEARCH_CONNECTION_NAME=your-search-connection-name" >> .env
echo "BING_CONNECTION_NAME=your-bing-connection-name" >> .env
echo "AI_SEARCH_INDEX_NAME=your-index-name" >> .env

# Step 3: Set up a Python virtual environment and install MCP and dependencies
uv venv
.venv\Scripts\activate
uv pip install "mcp[cli]" azure-identity python-dotenv azure-ai-projects

# Step 4: Run the Agent Service server script (Agent Service implementation)
# This will be used when configuring Claude Desktop with the Agent Service
# Example execution (adjust paths to your setup):
# python azure_ai_agent_service_server.py

# Step 5: For the Direct Azure AI Search path, create a separate environment and run the server
# This example shows the required commands and dependencies for the direct search path
uv pip install "mcp[cli]" azure-search-documents==11.5.2 azure-identity python-dotenv

# Step 6: Run the direct Azure AI Search server script
# Example execution (adjust paths to your setup):
# python azure_search_server.py

Additional configuration and examples

Configure Claude Desktop to use the MCP servers by providing the process details and environment variables shown below. You can run either the Agent Service path or the Direct Azure AI Search path depending on your preferred setup.

{
  "mcpServers": {
    "azure_ai_agent": {
      "command": "C:\\path\\to\\.venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\azure_ai_agent_service_server.py"],
      "env": {
        "PROJECT_CONNECTION_STRING": "your-project-connection-string",
        "MODEL_DEPLOYMENT_NAME": "your-model-deployment-name",
        "AI_SEARCH_CONNECTION_NAME": "your-search-connection-name",
        "BING_CONNECTION_NAME": "your-bing-connection-name",
        "AI_SEARCH_INDEX_NAME": "your-index-name"
      }
    },
    "azure_ai_search": {
      "command": "C:\\path\\to\\.venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\azure_search_server.py"],
      "env": {
        "AZURE_SEARCH_SERVICE_ENDPOINT": "https://your-service-name.search.windows.net",
        "AZURE_SEARCH_INDEX_NAME": "your-index-name",
        "AZURE_SEARCH_API_KEY": "your-api-key"
      }
    }
  }
}

Testing and usage tips

After starting Claude Desktop with the configured MCP servers, restart Claude Desktop to load the new configuration. Look for the MCP tools icon in the input area to access the search tools. Try queries that target your data, the web, or both, such as asking for information about topics present in your index or requesting up-to-date web results with citations.

Troubleshooting

If the MCP server does not appear or respond, check the following:

• Ensure environment variables and file paths are correct in your MCP configuration
• Verify the Python virtual environment is activated and dependencies are installed
• Review the server startup commands and confirm they run without errors
• Check Claude Desktop logs for MCP-related messages to identify issues with loading the servers

Notes on customization

You can customize how queries are processed and how results are presented. Extend or modify the tool implementations or add new tools to tailor the search experience to your workflow.

Available tools

azure_ai_agent_service_server

Server script that runs the Azure AI Agent Service integration, exposing the Azure AI Search and Bing web grounding capabilities.

azure_search_server

Server script for direct Azure AI Search integration, supporting keyword, vector, and hybrid search modes.