@ygen-phoenix/rag-mcp

MCP server that exposes a Postgres + Qdrant + Ollama RAG pipeline as tools for any MCP-compatible client (Claude Desktop, Cursor, custom agents, etc.). Communicates over stdio.

The embedding model is resolved per collection — the server reads the embedding_model column from the Postgres collections table on every call, so collections indexed with different models (e.g. mxbai-embed-large for one, nomic-embed-text for another) all work transparently.

Tools

| Tool | Purpose | |---|---| | list_collections | Lists all collections from Postgres with description, embedding model, and vector size. | | search_collection | Semantic search inside a specific collection. Auto-resolves the correct embedding model from the database. | | answer_question | Full RAG pipeline: retrieves context from the collection and synthesizes an answer with inline citations using the configured chat model. |

Install

npm install -g @ygen-phoenix/rag-mcp

Or run it ad-hoc with npx:

npx @ygen-phoenix/rag-mcp

Configuration

The server reads from environment variables. Copy .env.example to .env next to where you run the binary, or set them in your shell / MCP client config.

| Var | Required | Purpose | Example | |---|---|---|---| | DATABASE_URL | yes | Postgres connection (reads the collections table for per-collection embedding_model) | postgresql://user:[email protected]:5432/db | | QDRANT_BASE_URL | yes | Qdrant endpoint | http://localhost:6333 | | QDRANT_API_KEY | no | API key (Qdrant Cloud only) | eyJhbGciOi... | | OLLAMA_BASE_URL | yes | Ollama endpoint | http://localhost:11434 | | CHAT_MODEL | yes (for answer_question) | LLM used to synthesize the final answer | gpt-oss:20b |

Note: There is no global EMBEDDING_MODEL variable. Embedding models are resolved per collection from the collections.embedding_model column at query time.

Usage with Claude Desktop

Edit claude_desktop_config.json:

{
  "mcpServers": {
    "rag": {
      "command": "npx",
      "args": ["-y", "@ygen-phoenix/rag-mcp"],
      "env": {
        "DATABASE_URL": "postgresql://user:[email protected]:5432/db",
        "QDRANT_BASE_URL": "http://localhost:6333",
        "OLLAMA_BASE_URL": "http://localhost:11434",
        "CHAT_MODEL": "gpt-oss:20b"
      }
    }
  }
}

Usage with custom agents

In the agent's MCP configuration:

• Name: rag
• Transport: stdio
• Command: npx
• Args (one per line):

  -y
  @ygen-phoenix/rag-mcp

Set the environment variables in the agent's MCP config.

Database schema requirement

The server expects a Postgres collections table with at least these columns:

CREATE TABLE collections (
  id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  name            VARCHAR(100) NOT NULL UNIQUE,
  description     TEXT NOT NULL,
  embedding_model VARCHAR(255) NOT NULL,
  vector_size     INTEGER NOT NULL,
  distance        VARCHAR(20) NOT NULL DEFAULT 'Cosine',
  created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  updated_at      TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

Qdrant payload contract

For search_collection and answer_question to work:

• The Qdrant collection name must exactly match the name column in the Postgres collections table.
• The collection must have been indexed with the same embedding model that is stored in collections.embedding_model (the server reads that value and uses it to embed queries).
• Each point's payload should follow this shape:

{
  text: string                       // chunk content (required)
  fileName?: string                  // optional — used as citation source
  sourceId?: string                  // optional
  metadata?: Record<string, unknown> // optional
}

Local development

git clone <this-repo>
cd rag-mcp
npm install
cp .env.example .env
# edit .env

# dev mode (tsx — runs TypeScript directly)
npm run dev

# typecheck
npm run typecheck

# build for publish
npm run build

# run the compiled output
npm start

Publishing (maintainer notes)

npm run build            # outputs dist/
npm pack                 # inspect the tarball before publishing
npm publish --access public

The prepublishOnly hook builds dist/ automatically, and the "files" field in package.json whitelists what ships to npm (dist/, README.md, .env.example).

License

MIT