Azure AI Agent Service + Azure AI Search

This MCP server provides two paths to connect Claude Desktop with Azure search capabilities: use the Azure AI Agent Service for AI-enhanced document and web search, or connect directly to Azure AI Search with keyword, vector, or hybrid search. It enables you to search your private documents and the public web, with source citations where applicable, all through Claude Desktop.

How to use

You can run either the Agent Service implementation or the Direct Azure AI Search implementation to empower Claude Desktop with Azure-powered search across your data sources. The Agent Service option gives you AI-enhanced document search plus web search with citations. The direct search option connects straight to Azure AI Search for keyword, vector, or hybrid querying. After starting the server, Claude Desktop will expose search tools that you can invoke from the MCP interface to search your indexed content and the web.

How to install

Prerequisites you need to meet before installing are Python 3.10 or higher, Claude Desktop installed, and appropriate Azure resources (Azure AI Search with an index for vectorized text, plus any required connections for the Agent Service). You will run the MCP server locally in a Windows or macOS environment. Detailed steps below show how to set up either the Agent Service implementation or the Direct Azure AI Search implementation.

mkdir mcp-server-azure-ai-search
cd mcp-server-azure-ai-search

# Agent Service environment variables
# Create a .env file with your project and connection information

# On Windows, you can create the file with these lines in a shell:
# 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

# For the Direct Azure AI Search path, the env vars are different and live in a separate .env file.

Set up a Python virtual environment and install the MCP CLI plus the required Azure libraries. Run these commands in order.

uv venv
.venv\Scripts\activate
uv pip install "mcp[cli]" azure-identity python-dotenv azure-ai-projects

# Note: These commands are intended for a Windows environment; adapt paths as needed for macOS.

Agent Service setup and configuration

Prepare your Azure resources as follows. You will create an Azure AI Project, connect to Azure AI Search and to Bing Web Search, and retrieve the necessary connection names and index names. Then you will run the agent service server with the required environment variables.

# Example configuration for Claude Desktop MCP using the Agent Service
{
  "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"
      }
    }
  }
}
"],

Direct Azure AI Search setup and configuration

If you prefer direct Azure AI Search instead of the Agent Service, prepare a separate environment with the Azure service endpoint, index name, and API key. Then run the direct search server and configure Claude Desktop to point to it.

# Example configuration for Claude Desktop MCP using Direct Azure AI Search
{
  "mcpServers": {
    "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 Claude Desktop with the MCP configuration, verify the MCP tools appear (hammer icon) in the input area. Run sample searches to ensure you can query your Azure AI Search index and, if using the Agent Service, retrieve results with source citations. Try queries like searching for information in your Azure Search index and, if enabled, web results with citations.

Troubleshooting

If the MCP server does not appear or fails to start, check the following: verify the command paths and environment variables, ensure the virtual environment is activated, and confirm the server script paths are correct. You may also try running the server directly to surface errors, for example by executing the Python script that corresponds to the chosen implementation.

Notes and customization

You can customize how queries are processed, add new tools, and adjust response formatting to tailor results for Claude Desktop. You can also refine web search behavior to emphasize specific domains or sources.

Security and maintenance

Keep your Azure credentials secure by storing them in environment variables or a secrets manager. Rotate API keys and connection strings regularly and limit access to the MCP server to trusted clients.

Notes on licensing

This project is licensed under the MIT License.

Available tools

Azure AI Search Tool

Provides access to Azure AI Search for AI-enhanced document search with results aligned to indexed content.

Bing Web Grounding Tool

Enables web search with source citations using Bing Web Search integration.