RAG — Making Claude Know Your Documents

1 The Problem RAG Solves

Claude was trained on public data up to its knowledge cutoff. It knows nothing about your company's internal procedures, your SLAs, your product catalogue, or any private document. Even if you could give it all those documents in the prompt, the context window has limits and you would be paying to re-read the same documents on every query.

RAG (Retrieval-Augmented Generation) solves this: instead of stuffing all documents into the prompt, you store them in a searchable database, find only the most relevant ones for each query, and inject just those into the prompt.

2 The RAG Pipeline — Five Steps

Steps 1 and 2 happen at McpServer startup (seeding). Steps 3–5 happen on every document_search tool call.

3 What Are Embeddings?

An embedding is a list of numbers (a vector) that represents the meaning of a piece of text. Similar meanings produce vectors that are close together in space; different meanings produce vectors far apart.

In this project, SimulatedDenseEmbeddingService is used — it generates random-but-consistent vectors for each text (seeded by a hash of the text) — good enough for demonstration without an API key for a separate embedding service. It is registered in McpServer/Program.cs:

// McpServer/Program.cs — registered so DocumentSearchTools can inject IDocumentStore
builder.Services.AddSingleton<IEmbeddingService>(_ => new SimulatedDenseEmbeddingService(384));
builder.Services.AddSingleton<IVectorStore, InMemoryVectorStore>();
builder.Services.AddSingleton<IDocumentStore>(sp => {
    var vec = sp.GetRequiredService<IVectorStore>();
    var emb = sp.GetRequiredService<IEmbeddingService>();
    return new VectorDocumentStore(vec, emb);
});

4 The Vector Store — Similarity Search

A vector store stores (document, embedding) pairs and answers: "Which stored embeddings are closest to this query embedding?" The measure of closeness is cosine similarity: two vectors pointing in the same direction score 1.0 (identical meaning); perpendicular vectors score 0.0 (unrelated).

5 IDocumentStore — Higher-Level Abstraction

IDocumentStore wraps IVectorStore and IEmbeddingService together. You hand it a Document object with a Title and Content string. It calls the embedding service, converts the text to a vector, stores both together, and on search converts your query string to a vector for you.

public interface IDocumentStore
{
    Task AddAsync(Document document, CancellationToken ct = default);
    Task<IReadOnlyList<SearchResult>> SearchAsync(string query, int topK = 5, ...);
}

6 DocumentSearchTools — RAG as an MCP Tool

In this project, the RAG pipeline is exposed to Claude via an MCP tool rather than via a direct RagPipeline.QueryAsync() call. DocumentSearchTools is an instance class (injected with IDocumentStore via DI) that the McpServer hosts as an MCP tool. When Claude calls document_search, the McpServer invokes this class, which runs the vector search and returns matching snippets as JSON:

[McpServerToolType]
public class DocumentSearchTools
{
    private readonly IDocumentStore _store;

    public DocumentSearchTools(IDocumentStore store) => _store = store;

    [McpServerTool(Name = "document_search", ReadOnly = true)]
    [Description("Search the supply chain knowledge base for relevant documents.")]
    public async Task<string> SearchDocumentsAsync(
        [Description("Search query.")] string query,
        [Description("Number of results to return (1–5).")] int top_k = 3)
    {
        var results = await _store.SearchAsync(query, top_k);
        // serialise results to JSON and return
    }
}

7 Seeding the Knowledge Base at Startup

At McpServer startup, KnowledgeBaseSeeder.Seed() adds supply chain documents to the document store. Each document is embedded and indexed at that point:

// McpServer/Program.cs — runs after the host is built
var store  = host.Services.GetRequiredService<IDocumentStore>();
var logger = host.Services.GetRequiredService<ILogger<Program>>();
KnowledgeBaseSeeder.Seed(store, logger);

To add your own documents to the knowledge base, add them in KnowledgeBaseSeeder.Seed() using store.AddAsync(new Document { ... }). They will be available to Claude via the document_search tool on the next McpServer startup.

8 Summary

• RAG = find relevant documents, return their text as a tool result, let Claude synthesise an answer.
• Embeddings = numbers that represent meaning. Similar text → similar numbers.
• Vector store = a database that can find the most similar embeddings to a query.
• IDocumentStore wraps both: you hand it a Document, it handles embedding + storing + searching.
• In this project, RAG is exposed as the document_search MCP tool hosted in NexaFlowDemo.McpServer.
• The knowledge base is seeded at McpServer startup via KnowledgeBaseSeeder.Seed().
• The simulated embedding service generates deterministic random vectors (no embedding API needed for the demo).