How to build an MCP server for RAG

1mkdir mcp-rag-server && cd mcp-rag-server
2npm init -y
3npm install @modelcontextprotocol/sdk zod openai
4npm install @pinecone-database/pinecone  # or: npm install pg pgvector
5npm install -D typescript @types/node
6npx tsc --init

1// src/embeddings.ts
2import OpenAI from "openai";
3
4const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
5
6export interface DocumentChunk {
7  id: string;
8  text: string;
9  source: string;
10  chunkIndex: number;
11  embedding?: number[];
12}
13
14export function chunkText(
15  text: string,
16  source: string,
17  chunkSize: number = 800,
18  overlap: number = 200
19): DocumentChunk[] {
20  const chunks: DocumentChunk[] = [];
21  let start = 0;
22  let index = 0;
23
24  while (start < text.length) {
25    const end = Math.min(start + chunkSize, text.length);
26    chunks.push({
27      id: `${source}-chunk-${index}`,
28      text: text.slice(start, end),
29      source,
30      chunkIndex: index,
31    });
32    start += chunkSize - overlap;
33    index++;
34  }
35  return chunks;
36}
37
38export async function embedTexts(texts: string[]): Promise<number[][]> {
39  const response = await openai.embeddings.create({
40    model: "text-embedding-3-small",
41    input: texts,
42  });
43  return response.data.map(d => d.embedding);
44}
45
46export async function embedQuery(query: string): Promise<number[]> {
47  const [embedding] = await embedTexts([query]);
48  return embedding;
49}

1// src/vector-store.ts
2import pg from "pg";
3
4const pool = new pg.Pool({
5  connectionString: process.env.DATABASE_URL,
6});
7
8export async function initializeStore(): Promise<void> {
9  await pool.query(`CREATE EXTENSION IF NOT EXISTS vector`);
10  await pool.query(`
11    CREATE TABLE IF NOT EXISTS document_chunks (
12      id TEXT PRIMARY KEY,
13      text TEXT NOT NULL,
14      source TEXT NOT NULL,
15      chunk_index INTEGER NOT NULL,
16      embedding vector(1536) NOT NULL,
17      created_at TIMESTAMP DEFAULT NOW()
18    )
19  `);
20  await pool.query(`
21    CREATE INDEX IF NOT EXISTS chunks_embedding_idx
22    ON document_chunks USING ivfflat (embedding vector_cosine_ops)
23    WITH (lists = 100)
24  `);
25}
26
27export async function insertChunks(
28  chunks: { id: string; text: string; source: string; chunkIndex: number; embedding: number[] }[]
29): Promise<void> {
30  for (const chunk of chunks) {
31    await pool.query(
32      `INSERT INTO document_chunks (id, text, source, chunk_index, embedding)
33       VALUES ($1, $2, $3, $4, $5)
34       ON CONFLICT (id) DO UPDATE SET text = $2, embedding = $5`,
35      [chunk.id, chunk.text, chunk.source, chunk.chunkIndex, JSON.stringify(chunk.embedding)]
36    );
37  }
38}
39
40export async function searchSimilar(
41  queryEmbedding: number[],
42  topK: number = 5,
43  sourceFilter?: string
44): Promise<{ text: string; source: string; score: number }[]> {
45  const filterClause = sourceFilter ? `WHERE source = $3` : "";
46  const params = sourceFilter
47    ? [JSON.stringify(queryEmbedding), topK, sourceFilter]
48    : [JSON.stringify(queryEmbedding), topK];
49
50  const result = await pool.query(
51    `SELECT text, source, 1 - (embedding <=> $1::vector) AS score
52     FROM document_chunks ${filterClause}
53     ORDER BY embedding <=> $1::vector
54     LIMIT $2`,
55    params
56  );
57  return result.rows;
58}

1// src/index.ts
2import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
3import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
4import { z } from "zod";
5import { embedQuery } from "./embeddings.js";
6import { searchSimilar, initializeStore } from "./vector-store.js";
7
8const server = new McpServer({
9  name: "rag-document-server",
10  version: "1.0.0",
11});
12
13server.tool(
14  "search_documents",
15  "Search the knowledge base using natural language. Returns the most relevant document chunks with source citations and similarity scores. Use this to answer questions about the indexed documents.",
16  {
17    query: z.string().describe("Natural language search query"),
18    topK: z.number().min(1).max(20).default(5).describe("Number of results to return"),
19    source: z.string().optional().describe("Filter by source filename"),
20  },
21  async ({ query, topK, source }) => {
22    try {
23      const queryEmbedding = await embedQuery(query);
24      const results = await searchSimilar(queryEmbedding, topK, source);
25
26      if (results.length === 0) {
27        return { content: [{ type: "text", text: "No relevant documents found for this query." }] };
28      }
29
30      const formatted = results
31        .map((r, i) => `[${i + 1}] (score: ${r.score.toFixed(3)}) [Source: ${r.source}]\n${r.text}`)
32        .join("\n\n---\n\n");
33
34      return { content: [{ type: "text", text: formatted }] };
35    } catch (error) {
36      return {
37        content: [{ type: "text", text: `Error: ${error instanceof Error ? error.message : String(error)}` }],
38        isError: true,
39      };
40    }
41  }
42);

1server.tool(
2  "ingest_document",
3  "Add a document to the knowledge base for future searches. Chunks the text, generates embeddings, and stores vectors.",
4  {
5    text: z.string().describe("Full document text to index"),
6    source: z.string().describe("Source identifier (e.g., filename or URL)"),
7    chunkSize: z.number().default(800).describe("Characters per chunk"),
8  },
9  async ({ text, source, chunkSize }) => {
10    try {
11      const chunks = chunkText(text, source, chunkSize);
12      const texts = chunks.map(c => c.text);
13      const embeddings = await embedTexts(texts);
14
15      const chunksWithEmbeddings = chunks.map((c, i) => ({
16        ...c,
17        embedding: embeddings[i],
18      }));
19
20      await insertChunks(chunksWithEmbeddings);
21
22      return {
23        content: [{ type: "text", text: `Ingested "${source}": ${chunks.length} chunks indexed.` }],
24      };
25    } catch (error) {
26      return {
27        content: [{ type: "text", text: `Error: ${error instanceof Error ? error.message : String(error)}` }],
28        isError: true,
29      };
30    }
31  }
32);

1// Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json
2// Cursor: .cursor/mcp.json
3{
4  "mcpServers": {
5    "rag-documents": {
6      "command": "node",
7      "args": ["dist/index.js"],
8      "env": {
9        "OPENAI_API_KEY": "sk-...",
10        "DATABASE_URL": "postgresql://user:pass@localhost:5432/ragdb"
11      }
12    }
13  }
14}