rag-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@rag-mcp search the docs for the overpressure limit and read around the top hit"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
rag-mcp
An MCP server that gives a language model tools for searching a document index — built against rag-service.
pip install -r requirements.txt
RAG_MCP_SERVICE_URL=http://localhost:8000 python -m rag_mcp.serverWhat it does
The Model Context Protocol is how a model gets tools it can call. This server speaks MCP over stdio and exposes five:
Tool | What it returns | Cost |
| Ranked passages with document ids, scores and chunk ids | retrieval only |
| One chunk in full plus its neighbours, by id | none |
| An entire indexed document, in order | none |
| Chunk count, models, reranker, tracing state | none |
| A generated answer with sources, per-stage latency and USD cost | calls an LLM |
The tools are designed to chain: rag_search returns chunk ids, and
rag_read_around takes one and reads around it. The integration test drives
exactly that chain against a live service, so the promise in the tool
descriptions is checked rather than asserted.
Related MCP server: NOEMA-AI MCP Server
Connecting it to Claude Code
{
"mcpServers": {
"rag": {
"command": "python",
"args": ["-m", "rag_mcp.server"],
"env": {
"PYTHONPATH": "/absolute/path/to/rag-mcp/src",
"RAG_MCP_SERVICE_URL": "http://localhost:8000"
}
}
}
}Start rag-service first (docker compose up in that repo), then restart
Claude Code. The tools appear as rag_search, rag_answer and so on.
Variable | Default | Meaning |
|
| Where the RAG service listens |
|
| Seconds before a request gives up |
Three decisions worth explaining
The tool description is the API. A model picks a tool from its description
alone — it never sees the implementation. rag_search and rag_answer overlap,
so each description says when the other one is the better choice, and both
state what they cost. Tool descriptions here are written as carefully as the
code, because they are the part that determines whether the tools get used
correctly.
Errors are instructions, not tracebacks. If the service is down, the tool
returns "Cannot reach the RAG service at … Start it with docker compose up".
A model can act on that; it cannot act on a ConnectionRefusedError. Every
failure path is tested for the message it produces.
It talks HTTP, not Python. The server calls the RAG service over its public API instead of importing it. The two deploy independently, and this repo tests against a contract rather than someone else's internals.
This repo changed the other one
rag_read_around originally searched for the chunk id as a query string and
filtered the results. That cannot work — a chunk id appears in neither the
lexical nor the dense index — so it was a lookup that would quietly return
nothing. The fix belonged in the service, which gained real endpoints:
GET /chunks/{chunk_id}?context=N
GET /documents/{doc_id}Then the integration test, running the real service rather than a mock, failed
on rag_answer: asked for the overpressure limit, it returned the dry-run
paragraph. Two defects in the service's offline reader, both fixed there:
sentences were scored on raw token overlap, so stopwords decided the answer;
and the two best-scoring sentences were returned, when technical prose states
the subject in one sentence and the value in the next.
Both bugs were invisible to this repo's mocked tests, which is the argument for having an integration test at all.
Tests
pytest26 tests. 21 run against a mock HTTP transport and need nothing installed; 5
are integration tests that start a real rag-service in a background thread
with its offline provider and an in-process Qdrant — no container, no API key,
no network. They skip automatically if the service source isn't present:
RAG_SERVICE_SRC=/path/to/rag-service/src pytestRequirements
Python 3.10+ and mcp 2.x. The SDK renamed FastMCP to MCPServer in 2.0,
so requirements.txt pins mcp>=2.0,<3 rather than an open >=1.x that
resolves across the rename and breaks on a fresh install.
Limitations
rag_read_documenthas no size limit. A large document returns in full and will fill a context window. Chunk-level reads are the safe default.No write tools. Ingestion is deliberately absent: a model that can index documents can also poison the index.
No authentication. The server assumes the RAG service is reachable on a trusted network. Exposing it beyond localhost needs auth in front.
stdio transport only. No HTTP or SSE transport yet.
Tested against one implementation. The contract tests pin
rag-service's API shape; another service would need its own.
License
MIT — see LICENSE.
Available Tools
5 toolsrag_answerA
Ask the RAG service to generate an answer, with its sources and trace.
This calls a language model, so it is slower and costs money; prefer rag_search when you intend to read the passages and answer yourself. Returns the answer, the documents it drew on, the per-stage latency breakdown and the cost of the query in USD.
Inputs: question (required). Returns: result
rag_index_statsA
Report what is indexed and how the RAG service is configured.
Returns the collection name, chunk count, embedding and chat models, the active reranker and whether tracing is enabled. Call this first when a search returns nothing, to tell an empty index from a bad query.
Inputs: no named parameters. Returns: result
rag_read_aroundA
Read one indexed chunk in full, together with its neighbouring chunks.
Use this after rag_search when a passage is relevant but truncated and you need the surrounding text. chunk_id comes from rag_search output. context is how many chunks either side to include (0-5, default 1). This is an exact lookup by id, not another search, so it costs nothing to run.
Inputs: chunk_id (required), context. Returns: result
rag_read_documentA
Read an entire indexed document, in order.
Use when a document is clearly the right source and you want all of it rather than retrieved fragments. Large documents produce long output — prefer rag_search or rag_read_around when you only need one section.
Inputs: doc_id (required). Returns: result
rag_searchA
Search the indexed documents and return the most relevant passages.
Retrieval only: no text is generated, so this is the cheap and fast call. Prefer it when you want source material to read and quote yourself. Returns each passage with its document id, ordinal, relevance score and chunk_id; pass a chunk_id to rag_get_document to read around it. Use rag_answer instead only if you want the service to compose the answer.
Inputs: question (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool has a clearly distinct role: retrieval search, chunk-context reading, whole-document reading, index diagnostics, and LLM answer generation. The descriptions explicitly contrast rag_search with rag_answer and rag_read_around with rag_read_document, leaving little room for misselection.
All names use a consistent snake_case rag_ prefix, and most follow a verb or verb-noun pattern such as rag_search and rag_read_document. rag_index_stats is slightly noun-oriented rather than action-oriented, but it remains readable and predictable.
Five tools is well-scoped for a RAG retrieval server, with each tool covering a distinct part of the retrieval-and-answer workflow. There are no redundant tools and no obviously missing core operation within this small surface.
The set covers search, contextual reading, full-document reading, diagnostics, and generated answers, which are the core retrieval workflows. Minor gaps might include listing indexed documents or collections directly, but rag_index_stats and search largely compensate.
Related MCP Connectors
Build a RAG pipeline station by station and search your own documents with cited answers.
Public web tools for agents: product extraction, claim checks, webpage QA and ranked audits.
Ingest, manage, and retrieve documents for RAG-powered AI applications
Bounded tools for rendering, extraction, RAG, enrichment, local discovery and review analysis.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceExposes RAG and document intelligence pipelines as 8 composable tools for MCP-compatible clients, enabling querying, indexing, classifying, extracting, and assessing documents.1MIT
- AlicenseNot gradedqualityDmaintenanceExposes document ingestion, retrieval (vector, vectorless, hybrid), and multi-turn chat tools for a LangGraph-powered RAG pipeline with streaming answers.3MIT
- AlicenseNot gradedqualityDmaintenanceProvides document search, context retrieval, and indexing tools for AgentOS agents to query pharma documents with grounded citations.MIT
- FlicenseNot gradedqualityDmaintenanceEnables document Q&A and knowledge retrieval through hybrid semantic and keyword search, with tools for document ingestion, chunking, summarization, PII redaction, and RAGAS-based evaluation.-