THE RAG MCP

An enterprise-ready Model Context Protocol (MCP) server that exposes a Retrieval-Augmented Generation (RAG) tool. This server enables MCP-compatible clients (such as Claude Desktop or custom agents) to retrieve relevant context and source metadata from a Qdrant vector database using natural language queries.

🏗️ System Architecture & Features

This server runs as a standalone MCP host exposing a single tool: rag_tool.

graph TD
    A[MCP Client / Claude Desktop] -->|Call rag_tool| B[Lazy-Init Qdrant Retriever]
    B -->|Semantic Similarity Search| C[(Qdrant Vector Database)]
    C -->|Return Context Chunks| B
    B -->|Respond Context + Metadata| A

• Lazy Initialization: Postpones connections to the Qdrant database and the embedding provider until the first request is received. This allows the server to boot instantly and survive transient network or database outages during startup.
• Standardized Integration: Conforms to the MCP standard via FastMCP, allowing instant integration into LLM platforms like Claude Desktop.
• Robust Exception Containment: Captures configuration errors and connectivity issues, returning clean error responses to the caller instead of crashing the server.

⚙️ Environment Configuration

The server reads configuration options from the environment or a local .env file:

| Environment Variable | Type | Default | Description | | :----------------------------- | :----- | :--------- | :------------------------------------------------------------ | | QDRANT_URL | URL | Required | Absolute connection endpoint for the Qdrant database cluster. | | QDRANT_API_KEY | String | Required | Authentication token for your Qdrant instance. | | QDRANT_COLLECTION_NAME | String | "RAG" | Target database collection for vectors. | | EMBEDDING_MODEL_NAME | String | Required | Model identifier for generating query embeddings. | | BASE_URL_FOR_EMBEDDING_MODEL | URL | Required | Endpoint base URL for the OpenAI-compatible embedding API. | | OPENAI_API_KEY | String | Optional | API key for the embedding model provider. |

🚀 Getting Started

Prerequisites

Ensure you have uv installed (a fast Python package installer and resolver).

Running the Server

You can launch the server using uv to automatically handle dependencies:

# Start the MCP server over HTTP transport
uv run main.py

🔌 Connecting to Claude Desktop

To register this server in Claude Desktop, append its configuration to your claude_desktop_config.json:

Under Windows

{
  "mcpServers": {
    "the-rag-mcp": {
      "command": "uv",
      "args": ["run", "--path", "C:/Users/sj282/SJ/the_rag_mcp", "main.py"],
      "env": {
        "QDRANT_URL": "https://...",
        "QDRANT_API_KEY": "...",
        "QDRANT_COLLECTION_NAME": "RAG",
        "EMBEDDING_MODEL_NAME": "Qwen/Qwen3-Embedding-4B",
        "BASE_URL_FOR_EMBEDDING_MODEL": "https://api.siliconflow.com/v1",
        "OPENAI_API_KEY": "..."
      }
    }
  }
}

Under Linux/macOS

{
  "mcpServers": {
    "the-rag-mcp": {
      "command": "uv",
      "args": ["run", "--path", "/mnt/c/Users/sj282/SJ/the_rag_mcp", "main.py"],
      "env": {
        "QDRANT_URL": "https://...",
        "QDRANT_API_KEY": "...",
        "QDRANT_COLLECTION_NAME": "RAG",
        "EMBEDDING_MODEL_NAME": "Qwen/Qwen3-Embedding-4B",
        "BASE_URL_FOR_EMBEDDING_MODEL": "https://api.siliconflow.com/v1",
        "OPENAI_API_KEY": "..."
      }
    }
  }
}

🧠 Smart Retrieval Behavior

Once connected, the host LLM client will call the rag_tool tool when it determines that search context from the document library is required to fulfill a prompt.

Query Best Practices

• Do: Ask detailed, context-rich questions (e.g. "What are the primary differences between fine-tuning and retrieval-augmented generation?").
• Avoid: Simple keyword searches (e.g. "fine-tuning"), as semantic search models perform significantly better on complete thoughts and natural language queries.