rag-mcp-server

An MCP (Model Context Protocol) server that exposes Azure AI Search as a tool. Connect it to any MCP-compatible client (Claude Desktop, MCP Inspector, etc.) to give it hybrid vector + keyword search over your own document index.

What it does

Exposes a single MCP tool:

search_documents(query: str, top_k: int = 5) -> str

Generates an embedding for the query using Azure OpenAI, runs a hybrid search against Azure AI Search, and returns the top matching document chunks with source and metadata.

Prerequisites

Python 3.11+
An Azure AI Search index with a content_vector field
An Azure OpenAI embedding deployment (e.g. text-embedding-3-small)

Quick Start

Run locally with Python

# 1. Clone and enter the directory
git clone <repo-url>
cd rag-mcp

# 2. Create a virtual environment and install dependencies
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

# 3. Configure credentials
cp .env.example .env
# Edit .env and fill in your Azure endpoints and API keys

# 4. Start the server
python server.py

Server listens at http://localhost:8001/mcp.

Run with Docker

cp .env.example .env
# Edit .env and fill in your Azure endpoints and API keys

docker compose up --build

Environment Variables

Copy .env.example to .env and fill in the values:

Variable	Description
`AZURE_OPENAI_ENDPOINT`	Azure OpenAI resource endpoint
`AZURE_EMBEDDING_API_KEY`	API key for the embedding deployment
`AZURE_OPENAI_EMBEDDING_DEPLOYMENT`	Embedding model deployment name
`AZURE_SEARCH_ENDPOINT`	Azure AI Search service endpoint
`AZURE_SEARCH_API_KEY`	Azure AI Search admin or query key
`AZURE_SEARCH_INDEX_NAME`	Name of the search index to query

Testing with MCP Inspector

MCP Inspector is an interactive UI for calling MCP tools manually.

# Terminal 1 — start the server
python server.py

# Terminal 2 — open the inspector
npx @modelcontextprotocol/inspector

Open the URL printed by the inspector (e.g. http://localhost:5173), set transport to Streamable HTTP, enter http://localhost:8001/mcp, and click Connect. Navigate to the Tools tab to call search_documents.

Connect to Claude Desktop

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "rag-mcp": {
      "type": "streamable-http",
      "url": "http://localhost:8001/mcp"
    }
  }
}

Run the Automated Test

With the server running, execute the MCP client test:

python test.py

Passes three assertions: tool is registered, no server-side error, and results contain formatted document chunks.

Deploy to Azure Container Apps

See deploy.ps1 for a full Azure CLI deployment script. Fill in your resource group at the top of the file, then run:

.\deploy.ps1

The script builds and pushes the Docker image to ACR, creates a Container Apps environment, and deploys the server with a public HTTPS endpoint.