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

---

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.

Capability	Official Qdrant MCP	Qdrant RAG Build
Tools	2 (qdrant-store, qdrant-find)	33, organized in 6 namespaces
Collection management	Implicit auto-create only	Create with presets, aliases, snapshots, payload indexes
File ingestion	No — raw text only	PDF, DOCX, XLSX, PPTX, MD, HTML, CSV, TXT, URL, directories
Chunking	No	Structural, per format, with configurable presets
Search	Simple dense	Dense + sparse with RRF fusion, filters, rerank, MMR, multi-query
Citations	No	Stable citation contract (doc, page/section, score)
Guided setup	Environment variables	Conversational wizard that provisions everything
Clients	stdio (local Claude)	stdio + remote HTTP — Claude Code, Claude Desktop, and claude.ai (v1); ChatGPT is v2

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

Area	Decision	Why
Language	Python 3.12 + uv	Mature RAG ecosystem; deep domain expertise; uvx qdrant-rag-build-mcp = one-command install
MCP framework	Official MCP SDK, MCPServer (mcp>=2.1.0)	Same code serves stdio (Code, Desktop) and streamable HTTP (claude.ai); maintained by the MCP project itself. The SDK renamed FastMCP→MCPServer in v2.0.0 (2026-07-28) — this project targets the current class, no legacy constraint (see ADR 0001)
Dense embeddings	Two local tiers via fastembed — paraphrase-multilingual-MiniLM-L12-v2 (fast, 0.22 GB) and multilingual-e5-large (quality, 2.24 GB) — plus OpenAI / Cohere / Ollama via config	Both natively supported in fastembed today, zero extra dependency, multilingual. bge-m3 was the original candidate but is not usable: fastembed PR #602 adding it has been open since Feb 2026, still unmerged and blocked on an architecture debate with no ETA as of Aug 2026. Revisit once it lands.
Sparse embeddings	BM25 / miniCOIL via fastembed	Hybrid search with no extra infrastructure; native fusion via the Qdrant Query API
Rerank	Local cross-encoder via fastembed; Cohere Rerank and /v1/rerank (llama.cpp) optional	Never assume a runtime "already has" rerank — a lesson paid for in production (§11)
Parsing	PyMuPDF, python-docx, openpyxl, python-pptx, trafilatura	Fast, no system binaries, pip-installable on any OS
Config	Versionable YAML profiles (~/.qdrant-rag-build/profiles/*.yaml)	The wizard writes profiles; users can edit, version, and share them
Distribution	PyPI (uvx/uv) + Claude Desktop .mcpb bundle + Docker image (for the claude.ai deployment recipe) + docker-compose for local Qdrant	Three real v1 install paths — claude mcp add for Code, one-click .mcpb for Desktop, tunnel-or-always-on-host for claude.ai — plus a convenience compose file for Qdrant itself

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

Tool	What it does
collection_create	Creates a collection with presets (dense, hybrid, multi-tenant); named vectors + sparse configured correctly by default
collection_list	Inventory of all collections
collection_info	Detail: schema, size, index config, optimization status
collection_delete	Two-step confirmation delete (exact name required as argument)
alias_set	Aliases for zero-downtime reindexing (blue/green pattern)
payload_index_create	Payload indexes for filters declared by the wizard or the user
snapshot_create	Collection backup
snapshot_restore	Collection restore

Ingestion

Tool	What it does
ingest_text	Direct text with metadata — the "semantic memory" use case of the official MCP, done properly
ingest_file	Single file (PDF, DOCX, XLSX, PPTX, MD, HTML, CSV, TXT); returns an ingestion quality report
ingest_directory	Recursive batch with glob/exclusions; creates a job with queryable progress
ingest_url	Web page → clean main content (trafilatura), no boilerplate
job_status	Job progress: files done/failed/skipped, reconciled counters
document_list	Inventory by source document
document_delete	Delete/re-ingest a single document without touching the rest

Search

Tool	What it does
search	Dense semantic search with optional payload filters
search_hybrid	Dense + sparse with native RRF fusion (Query API with prefetch) — the recommended default
search_rerank	Hybrid + cross-encoder over the top-N; maximum precision
search_multi_query	Several reformulations (generated by the client LLM) fused into one ranking
find_similar	Points similar to a given one
recommend	Recommendation with positive/negative examples (native Qdrant API)

RAG context

Tool	What it does
get_context	The centerpiece: search + dedup + MMR + token budget → formatted context block with numbered citations, ready for the client LLM to answer with
expand_context	Neighboring chunks of a result (previous/next in the same document) for continuity
get_document	Full source document (or a page/section range) behind a citation

Wizard

Tool	What it does
setup_start	Starts the setup session; returns the first question with options and a recommendation
setup_answer	Records the answer, validates it (does Qdrant respond? does the API key work?), returns the next question
setup_apply	Executes the agreed plan: collection + indexes + profile + smoke test; returns a final report
profile_list	Lists saved profiles
profile_use	Activates a saved profile (demo, work, project X…)

Admin

Tool	What it does
health	Qdrant connectivity, embedding model loaded, version, active transport
stats	Points, documents, disk size, distribution by source/type
estimate	Before ingesting: estimated chunk count, storage, embedding API cost if applicable
config_get	Effective configuration of the active profile (secrets masked)

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)

#	Question	What it decides
1	What are you putting into the RAG? (personal docs / team KB / technical docs / notes)	Chunking preset and payload schema
2	Where is your Qdrant? (local docker / Qdrant Cloud / don't have one yet)	Connection; if "don't have one," one-command docker instructions and re-validation
3	Local embeddings or API? (local fast / local quality / OpenAI / Cohere / Ollama)	Dense provider and speed/quality tier; API key validated on the spot if applicable
4	Corpus language(s)?	Confirms multilingual model choice and sparse analyzer
5	Hybrid search? (recommended: yes)	Sparse vector in the collection schema
6	Rerank? (local / API / no)	Cross-encoder and its latency cost, explained honestly
7	What filters will you use? (date, author, type, folder…)	Payload indexes created by default
8	Collection and profile name	Naming + profile file

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."

Format	Parser	Quality treatment
PDF	PyMuPDF	Correct reading order, repeated header/footer detection and removal, tables converted to Markdown, text-quality pre-flight (valid-character ratio) before accepting a page
DOCX	python-docx	Heading hierarchy preserved as a metadata breadcrumb; structured lists and tables
XLSX	openpyxl	Per sheet; data regions detected; rows serialized with their headers ("Product: X · Price: Y") — never raw CSV
PPTX	python-pptx	Per slide: title + body + speaker notes
MD / HTML	native / trafilatura	Chunked by headings; for web pages, main content only (no nav, cookies, footers)
CSV / TXT	stdlib	CSV as header-labeled rows; TXT by paragraph with a token window

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.

Phase	Focus	Duration	Definition of done
F0	Spec and skeleton	~1.5 weeks	Repo + CI + package structure. JSON schemas for all 33 tools frozen and reviewed (design all 33 up front, even if implemented in later phases). ADRs for the §3 decisions. uvx qdrant-rag-build-mcp starts, health responds from Claude Code (stdio) and from claude.ai (HTTP via tunnel).
F1	Qdrant core	~2 weeks	Full collections namespace, ingest_text, dense search, config profiles, read-only mode. E2e demo from Claude Code: create a collection, save notes, search them. Already a superset of the official MCP.
F2	Professional ingestion	~3 weeks	All 8 formats with their quality treatment, structural chunking, dedup, jobs with progress, ingestion reports. A mixed folder of 100 real documents ingested cleanly, with a faithful report (reconciled counters) and idempotent re-ingestion.
F3	Elite retrieval	~2 weeks	Hybrid RRF, rerank, MMR, filters, get_context with the citation contract. Golden-corpus evals show a measurable improvement for hybrid+rerank over dense; zero phantom sources in citations.
F4	Wizard	~2 weeks	State machine, live validation of every answer, setup_apply with smoke test, multiple profiles. An outside tester builds their own RAG in under 10 minutes by conversation alone, no docs opened. Record the demo here.
F5	Quality and observability	~1.5 weeks	Eval suite in CI with thresholds, stats/estimate, snapshots, verified client compatibility matrix. CI green with blocking evals; benchmarks published in the docs.
F6	Launch	~2.5 weeks	Full docs, a polished landing page, README with demo recording, PyPI + .mcpb bundle + Docker image, MCP registries, launch post. Installable in one command (or one drag-and-drop) across all three v1 environments; listed in ≥4 registries; Show HN submitted.

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.

Lesson paid for	How Qdrant RAG Build bakes it in
MMR that re-embedded during retrieval caused a real production OOM	MMR always reuses the vectors Qdrant returns; embedding in the search path is forbidden
Internal metadata bloated the payload until it truncated the actual sources (twice, for different reasons)	Closed, versioned citation contract; pipeline metadata never reaches the LLM's context
Assumed the local runtime "had rerank" — it never worked, and the fallback hid it	Rerank is explicit per verifiable provider; health actually checks that the configured reranker responds
Threads + fork in the same process → a real ingestion deadlock	Ingestion concurrency with a single model (async + worker process); never mix ThreadPoolExecutor with fork
Jobs marked "completed" at 40% because the child process died silently	A job is only completed if the counters reconcile (expected = processed + justified failures)
OCR would hang for 45s only to discard the document anyway	Cheap quality pre-flight before any expensive work; per-document time budgets
NER quality turned into endless domain-specific whack-a-mole	NER is out of scope for v1 — a decision, not an oversight

Open risks

Risk	Mitigation
Scope creep — the temptation to rebuild the entire enterprise RAG	The "out of scope" list in §2 is contractual; any addition requires removing something else or justifying a v2
Remote-deployment friction for claude.ai (tunnel or always-on host is one more moving part than local stdio)	Local stdio (Code, Desktop) stays the happy path and needs zero of this; claude.ai's setup is one guided doc page, and it's the only remote client v1 needs — no Developer-Mode/paid-plan complexity, unlike ChatGPT
Excluding ChatGPT narrows v1's audience to the Claude ecosystem	Deliberate trade-off, not an oversight: claude.ai already covers the "remote, no-install" audience on every plan including Free; ChatGPT's Developer-Mode-plus-paid-plan gate adds real friction without expanding v1's reach much further — revisit in v2 once the core is proven
fastembed PR #602 (bge-m3 support) stays blocked indefinitely	v1 does not depend on it — uses multilingual-e5-large natively; revisit as a v2 upgrade if the PR lands, with the option of contributing to it directly
MCP protocol or Qdrant Query API changes	Always-current official SDK; per-release compatibility matrix; thin facade = small surface for change
33 tools saturate the client's context	Descriptions optimized for tool-choice conciseness; per-profile tool sets (e.g. hide admin tools in daily use)
Abandonment from lack of time (risk #1 of every side project)	Phases of ≤3 weeks with a demo at the end; F1 alone is publishable as "the official MCP, but better" if everything else slips

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.