playbooks

home / mcp / azure ai agent service + azure ai search mcp server

Azure AI Agent Service + Azure AI Search MCP Server

Connect Claude Desktop to Azure AI Search using Agent Service or direct search, delivering AI-enhanced document and web results.

Installation
Add the following to your MCP client configuration file.

Configuration

View docs
{
  "mcpServers": {
    "0lovesakura0-mcp-server-azure-ai-agents-main": {
      "command": "C:\\path\\to\\.venv\\Scripts\\python.exe",
      "args": [
        "C:\\path\\to\\azure_ai_agent_service_server.py"
      ],
      "env": {
        "AI_SEARCH_INDEX_NAME": "your-index-name",
        "BING_CONNECTION_NAME": "your-bing-connection-name",
        "MODEL_DEPLOYMENT_NAME": "your-model-deployment-name",
        "AI_SEARCH_CONNECTION_NAME": "your-search-connection-name",
        "PROJECT_CONNECTION_STRING": "your-project-connection-string"
      }
    }
  }
}

You can extend Claude Desktop with Azure AI search capabilities by running a dedicated MCP server that connects to Azure AI Search and, optionally, Bing web search. This server lets you query your private documents with AI-enhanced results or search the web with citations, all from Claude Desktop.

How to use

You will run one or more MCP server instances locally and connect Claude Desktop to them. Start the server(s) in your environment, then configure Claude Desktop to load the MCP endpoints. Once connected, you can perform queries that leverage Azure AI Search for your indexed documents and, if you choose the Agent Service route, access Bing web search with source citations to enrich results.

How to install

Prerequisites you need before starting:

Install and run the Azure AI Agent Service MCP server

# Create a project directory
mkdir mcp-server-azure-ai-search
cd mcp-server-azure-ai-search

# Create a .env file with required project details (placeholders shown)
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

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

# Run the agent service MCP server (example command)
python azure_ai_agent_service_server.py

Install and run the Direct Azure AI Search MCP server

# Prepare environment for direct Azure AI Search integration
echo "AZURE_SEARCH_SERVICE_ENDPOINT=https://your-service-name.search.windows.net" > .env
echo "AZURE_SEARCH_INDEX_NAME=your-index-name" >> .env
echo "AZURE_SEARCH_API_KEY=your-api-key" >> .env

# Install dependencies
uv pip install "mcp[cli]" azure-search-documents==11.5.2 azure-identity python-dotenv

# Run the direct Azure AI Search MCP server (example command)
python azure_search_server.py

Configuring Claude Desktop

{
  "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_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 the server

After starting the server, restart Claude Desktop to load the new configuration. Look for the MCP tools icon (hammer) in the bottom-right of the input field, then try queries that exercise document search, web search, or a mix of both.

Troubleshooting

If the MCP server does not appear or fails to respond, check your environment and paths. Verify that all required environment variables are correctly configured for each server. If authentication or Azure service connections fail, re-authenticate with the corresponding Azure services and confirm that your Azure resources (AI Search index and associated connections) exist and are accessible.

Notes on customization

You can customize tool behavior, add new tools, or adjust response formatting to fit your workflow. Refer to the agent and search server code paths to extend how queries are processed and how results are returned to Claude Desktop.

Security and credentials

Keep all credentials and connection strings secure. Do not commit .env files to version control. Use Azure Key Vault or environment-level secret management where possible and rotate credentials regularly.

License

This project is licensed under the MIT License.

Available tools

Azure AI Agent Service

Integrates with Azure AI Agent Service to provide AI-enhanced document search via Azure AI Search and web search via Bing with citations.

Azure AI Search Tool

Search indexed documents with AI-enhanced results using the Azure AI Search integration.

Bing Web Grounding Tool

Perform web searches with source citations through Bing and grounding in search results.