Qdrant RAG Build

The Qdrant MCP server that builds a full RAG pipeline through conversation.

Unofficial, community-built — not affiliated with or endorsed by Qdrant.

The official Qdrant MCP server exposes 2 tools (qdrant-store, qdrant-find). Qdrant RAG Build exposes 33 tools across 6 namespaces — a production-grade RAG system managed entirely through an MCP conversation — plus a conversational setup wizard that takes a user from zero to a working, well-configured RAG collection in one chat, no documentation required.

Elevator pitch: "Connect your AI to Qdrant and have a production-grade RAG running in one conversation." Not another Qdrant wrapper — RAG-in-a-box via MCP.

Package: qdrant-rag-build-mcp · License: Apache-2.0 · Status: planning complete, implementation not started.

Table of contents

1. Vision and market gap

2. Locked decisions

3. Architecture

4. Tool catalog

5. The conversational wizard

6. Ingestion pipeline

7. Elite retrieval

8. Quality and evals

9. GitHub authority

10. Development phases

11. Inherited lessons and risks

12. Name, license, and first step

Related MCP server: RAG Knowledge Base MCP Server

1. Vision and market gap

Thesis: today, connecting an LLM to Qdrant via MCP gives you a toy semantic memory. No collection management, no file ingestion, no hybrid search, no rerank, no citations, no guided configuration. All of that exists in bespoke enterprise RAG systems — nobody has packaged it as an MCP server you install in one command.

2. Locked decisions

Scope. Full retrieval + Qdrant management + very high-quality ingestion of common formats (PDF, DOCX, Excel, PPTX, MD, HTML, CSV, URL). Clean, RAG-optimal content is the project's signature.

Target clients. v1 is the full Claude family: Claude Code, Claude Desktop, and claude.ai (web). Code and Desktop are stdio, local, and close to one-click install (§3). claude.ai needs remote HTTP by protocol necessity (a browser can't spawn a local process) — but that's a modest addition, not a new category of work: the official SDK already speaks streamable HTTP, and v1 only needs a bearer token, not full OAuth 2.1 (§3), plus one deployment guide for reaching a public HTTPS URL. ChatGPT stays out of v1. Unlike claude.ai it requires Developer Mode (an explicit risk warning to accept) and a paid plan, with no free tier at all — friction that doesn't serve "prioritize Claude," so it's deferred to v2.

Project goal. An outstanding open-source tool: portfolio centerpiece and GitHub-authority engine. Documentation, CI, and DX quality are not optional — they are the product.

Out of scope (v1). PST/email ingestion, heavy OCR, NER/entity extraction, server-side LLM generation (the client is the LLM), a bespoke UI. Each exclusion is justified in §11.

3. Architecture

One Python binary, three clean layers. The MCP server is a thin facade; all logic lives in a testable core with no MCP dependency (which also unlocks a future CLI or SDK without touching anything).

flowchart LR
    subgraph Clients
      CC[Claude Code / Desktop<br/>stdio]
      WEB[claude.ai<br/>HTTPS + bearer token]
    end
    subgraph QRB["Qdrant RAG Build"]
      T[Transport<br/>stdio · streamable HTTP]
      F[MCP facade<br/>33 tools · validation]
      CORE[RAG core<br/>ingestion · retrieval · wizard]
      EMB[Embeddings<br/>local fastembed · external APIs]
    end
    Q[(Qdrant<br/>local · cloud)]
    CC --> T
    WEB --> T
    T --> F --> CORE
    CORE --> EMB
    CORE --> Q

Technical decisions

Why the wizard is a state machine, not MCP elicitation. Elicitation support varies across MCP clients and SDK versions, including within the Claude family. A plain state machine driven by ordinary tools works identically everywhere, requires no special capability to be present, and carries over unchanged if v2 adds clients with different elicitation support. Locked regardless of transport scope.

v1 authentication decision. Full OAuth 2.1 for MCP (authorization server, PKCE, Dynamic Client Registration / Client ID Metadata Documents, issuer validation, refresh tokens) is real, multi-week engineering work with no budget in v1 — and claude.ai's own connector setup treats OAuth as an optional advanced field, not a requirement. v1 ships a static per-profile bearer token for the HTTP path: generated by the wizard, stored in the profile YAML, sent as Authorization: Bearer <token>. stdio (Code, Desktop) needs no auth at all — it's a local process with no network exposure. Full OAuth 2.1 stays a documented v2 upgrade, revisited if/when ChatGPT (whose ecosystem leans harder on it) comes into scope.

Deployment model: one user, one server

MCP does not connect a server "to the AI" in the abstract — it connects to the client application that hosts the model (Claude Desktop, Claude Code, claude.ai). That client is what keeps the connection alive, hands the model the list of available tools, intercepts the model's tool-call decisions, and executes them against the server. To the end user this reads as "I'm talking to Claude and it manages my Qdrant" — a fair simplification — but the client, not the model, is what's actually wired to the server.

There is no shared/multi-tenant server in v1 scope. Each user runs their own server, and the same local process serves all three v1 clients:

• Claude Code / Claude Desktop: the server runs as a local stdio child process on the user's own machine, launched by the client from its config. Real filesystem access, scoped to allowlisted directories — standard MCP stdio behavior, nothing this project has to build.

• claude.ai: the same local process, exposed over HTTPS through a tunnel (cloudflared) or a small always-on host (a $5 VPS, Fly.io, Railway) running the same Docker image — not a separate cloud deployment or a shared server. Filesystem access is identical to the local case when it's the user's own tunneled machine; only the transport reaching it differs. Available on every claude.ai plan, including Free (one connector).

• Consequence: ingest_directory / ingest_file behave the same across all three clients, as long as the user's own server (and, for claude.ai, the tunnel) is running. No file-upload machinery needed anywhere — the server always has direct disk access by construction.

• Installing it, once:

  • Claude Desktop: drag one .mcpb file into Settings → Extensions. Zero terminal.

  • Claude Code: claude mcp add qdrant-rag-build -- uvx qdrant-rag-build-mcp. One line.

  • claude.ai: Settings → Connectors → Add, paste the server's HTTPS URL and bearer token. Needs the server (and tunnel, if using the laptop recipe) already running first — same as any remote MCP connector, by protocol necessity, not a choice this project made.

  • From there, the wizard makes configuring the RAG fully conversational — creating collections, choosing embeddings, ingesting documents, searching — with zero further technical steps, on any of the three.

v2: ChatGPT (deliberately still out)

ChatGPT needs the same remote-HTTP shape as claude.ai — nothing new there technically. What keeps it out of v1 is friction specific to ChatGPT itself: Developer Mode must be explicitly enabled (with a warning about running third-party code), and custom connectors require a paid plan (Plus/Pro/Business/Enterprise/Edu) — there is no ChatGPT Free path at all, unlike claude.ai's free-tier-inclusive connectors. None of that serves "prioritize Claude." v2 adds a ChatGPT-specific connector guide and, if it turns out to matter, revisits full OAuth 2.1 (ChatGPT's ecosystem leans harder toward it than claude.ai's does).

4. Tool catalog

The heart of the project. Six namespaces, predictable names, descriptions written for the LLM (when to use a tool, not just what it does). Every destructive tool requires explicit confirmation, and a global read-only mode exists.

Collections

Ingestion

Search

RAG context

Wizard

Admin

5. The conversational wizard

The differentiator. A state machine on the server: every tool call returns the next question with its options and a reasoned recommendation; the client's LLM relays it to the user naturally and passes the answer back. No elicitation, no dependency on any specific client — the conversation is the interface.

stateDiagram-v2
    direction LR
    [*] --> Discover
    Discover --> Validate : setup_answer
    Validate --> Discover : next question
    Validate --> Summary : all answered
    Summary --> Apply : user confirms
    Apply --> SmokeTest
    SmokeTest --> [*] : report + saved profile

Question script (fixed order, recommendation on every step)

Wizard success definition. A user who has never seen Qdrant, in a conversation under 10 minutes, ends up with: a well-schematized collection, working embeddings, a saved profile, one example document ingested, and a test search returning cited results. The smoke test's final report is the proof — and a recording of that conversation is the README's cover.

6. Ingestion pipeline

The quality signature: clean, RAG-optimal content, per format, with a quality report on every ingestion. Never "dump whatever the parser spits out."

Cross-cutting rules

• Structure first, tokens second. Cut along document structure (section, sheet, slide) first, and only subdivide by token budget (with overlap) when a unit exceeds it. Every chunk carries a breadcrumb ("Manual › Chapter 3 › Installation").

• Dedup by normalized content hash at the chunk level, plus per-document idempotency: re-ingesting a file updates it, never duplicates it.

• Minimal, versioned citation contract. The citation payload (document, page/section, date, source) is a closed field set. Internal pipeline metadata never reaches the LLM's context — this project has twice paid for the bug where metadata bloat truncates the actual sources (§11).

• Always report ingestion results. Chunks created, pages discarded for quality and why, duplicates detected. Transparency is part of quality.

• Text sanitization (surrogates, control characters, broken encodings) before embedding — learned the hard way from real-world PST files.

7. Elite retrieval

• Hybrid by default: dense (multilingual embeddings) + sparse (BM25/miniCOIL) with native RRF fusion via the Qdrant Query API (prefetch + fusion) — no extra infrastructure.

• Optional rerank with a cross-encoder over the top-50 → top-N. Local via fastembed, or API (Cohere, llama.cpp's /v1/rerank).

• MMR for diversity, reusing the vectors Qdrant already returns (with_vectors=true). Never re-embed during retrieval — that mistake caused a real production OOM in this project's predecessor.

• First-class payload filters: date (well-bounded ranges, end-of-day inclusive in lte), source, type, author — over indexes created by the wizard.

• get_context as the flagship tool: orchestrates hybrid → rerank → MMR → token budget → formatted block with numbered citations [1][2]. Hard guarantee: only what actually made it into the context gets cited — never phantom sources.

• Generation stays on the client. The server never calls an LLM: it delivers the best possible context and the user's own model (Claude, GPT) writes the answer. This keeps the server cheap, fast, and free of mandatory third-party API keys.

8. Quality and evals

• Golden corpus in the repo: 15–20 varied documents (PDF with tables, a real spreadsheet, a noisy web page) + ~50 questions with annotated relevant chunks.

• Retrieval metrics in CI: recall@k, MRR, and nDCG over the golden corpus, with thresholds that break the build on regression. Dense vs. hybrid vs. hybrid+rerank published in the docs — the numbers sell the project.

• Layered tests: unit tests for the core with no Qdrant dependency, integration tests against Qdrant in a container (testcontainers), and e2e tests of the MCP protocol using the SDK's test client. Torture files per format (scanned PDF, Excel with merged cells, garbage HTML).

• Compatibility matrix verified per release: Claude Code, Claude Desktop, and claude.ai, documented with screenshots. ChatGPT joins this matrix in v2.

9. GitHub authority

For the portfolio goal, the repository is the product as much as the code. Launch checklist:

• A README that converts. A recording of the wizard building a RAG in one real conversation (vhs/asciinema), a 3-line uvx quickstart, badges (CI, coverage, PyPI, license), a comparison table against the official MCP, and published benchmarks.

• A landing page. A dedicated, polished static page — separate from the README and the docs site — with a hero, the comparison table against the official Qdrant MCP, the wizard demo recording, install CTAs for all three v1 clients, and F5's benchmark numbers. This is what the launch post and social links point to.

• Documentation. An mkdocs-material site: a guide per client (Claude Code, Claude Desktop, claude.ai — including the bearer-token connector walkthrough), a cookbook ("RAG over your own docs," "team memory"), a complete reference for all 33 tools, public ADRs.

• Visible engineering. CI with ruff + mypy strict + pytest + coverage, automated semver releases (release-please), CHANGELOG, issue/PR templates, CONTRIBUTING, Code of Conduct, GitHub Discussions enabled.

• Distribution and launch. PyPI + Claude Desktop .mcpb bundle + Docker image + compose stack (Qdrant included). Listed on the official MCP registry, Smithery, Glama, PulseMCP, and awesome-mcp-servers. Launch: a technical write-up + Show HN + r/LocalLLaMA + X, with the wizard recording as the hook.

10. Development phases

Side-project pace (evenings/weekends). Every phase ends in something demonstrable — never two phases open at once.

Total: ~14.5 weeks (~3.5 months) at a realistic side-project pace, with demonstrable milestones every two weeks to keep momentum.

11. Inherited lessons and risks

The quiet competitive advantage: this plan inherits errors already paid for in a real enterprise RAG system handling terabytes of data. Every lesson is baked into the design from day one, not patched in later.

Open risks

12. Name, license, and first step

Name: Qdrant RAG Build (package qdrant-rag-build-mcp) — chosen to stay close to this repository's own working name instead of an invented brand. Naming went through two earlier rounds: Quiver was dropped for colliding with the unrelated "Quiver Quantitative" MCP namespace (bolshchikov/quiver-mcp, pipeworx-io/mcp-quiver, jsconiers/quiver-quant-mcp); Vectorsmith was verified clean but overridden by an explicit preference to keep the name recognizable against the repo. That means accepting the trade-off the original plan had flagged — a "qdrant"-prefixed name can read as an official Qdrant project — mitigated by stating "unofficial, community-built" plainly in the README tagline and docs site. The literal slug qdrant-rag-mcp is already an active, unrelated project (ancoleman/qdrant-rag-mcp) and was deliberately avoided; qdrant-rag-build / qdrant-mcp-rag-build are verified clean on PyPI and GitHub (August 2026).

License: Apache-2.0 — same as Qdrant, with a patent grant, the license enterprises reading your profile expect to see.

First concrete step: F0 starts by writing the JSON schemas for all 33 tools before a single line of server code. The catalog in §4 is the spec; freezing it first avoids mid-flight redesigns and produces a publishable design document from week one.

References: qdrant/mcp-server-qdrant (official server, 2 tools) · fastembed PR #602 (bge-m3 support, open) · MCP Bundles (.mcpb) toolkit · Custom connectors using remote MCP (claude.ai) · v2 reading: ChatGPT Developer Mode, MCP and connectors in OpenAI

Plan v1.3 · locked 2026-08-24 · v1 covers the full Claude family (Code, Desktop, claude.ai — stdio + bearer-token HTTP); ChatGPT specifically deferred to v2 for its own Developer-Mode/paid-plan friction, not a technical constraint shared with claude.ai. Written with lessons learned from the IA_EmailsContext enterprise RAG project as a reference.