How do I use mcp-agentic-rag?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-agentic-rag search my documents for information on text classification" 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.

mcp-agentic-rag

by sampathpulukurthi

Overview Schema Source Related Servers Discussions Admin

Python

Local

Agentic RAG MCP

A minimal FastAPI + FastMCP project that combines local RAG retrieval with Firecrawl web fallback.

What this project does

Loads a FastAPI application for document ingestion and vector queries.
Uses ChromaDB for local vector storage and SentenceTransformers for embeddings.
Provides an MCP tool server via fastmcp to expose RAG tools over stdio transport.
Falls back to Firecrawl web search only when the local vector DB returns no documents.

Related MCP server: RAG MCP Server

Repository structure

app/ - application source code
- api/ - FastAPI routes and schemas
- core/ - RAG logic, embeddings, fallback helper
- services/ - ChromaDB service integration
- mcp/ - FastMCP server entrypoint
scripts/ - utility scripts (seed data, etc.)
data/ - storage and persistence directories
.env.example - environment variable template
pyproject.toml - project dependencies and packaging config

Setup for a new user

1. Clone the repository

git clone https://github.com/sampathpulukurthi/agentic-rag-mcp.git
cd agentic-rag-mcp

2. Create a Python virtual environment

python3 -m venv .venv
source .venv/bin/activate

3. Install dependencies

python -m pip install -e .

4. Create environment variables

cp .env.example .env

Edit .env and set:

FIRECRAWL_API_KEY=your_firecrawl_api_key_here

5. Run the FastAPI backend

uvicorn app.main:app --host 127.0.0.1 --port 8000 --reload

Then verify:

curl http://127.0.0.1:8000/api/health

6. Run the MCP server

With the virtualenv active:

.venv/bin/python -m app.mcp.server

This starts the FastMCP server named mcp-agentic-rag using stdio transport.

How to use

Ingest documents

curl -X POST http://127.0.0.1:8000/api/ingest \
  -H "Content-Type: application/json" \
  -d '{"documents": [{"id":"doc1","text":"Machine learning models can classify text.","metadata":{"topic":"ml"}}]}'

Query local vector store

curl -X POST http://127.0.0.1:8000/api/query \
  -H "Content-Type: application/json" \
  -d '{"query_text":"How do text classification models work?","k":3}'

Query with fallback to Firecrawl

curl -X POST http://127.0.0.1:8000/api/query_with_fallback \
  -H "Content-Type: application/json" \
  -d '{"query_text":"What is machine learning?","k":5}'

If the vector store returns no documents, the endpoint will return fallback: true and web_results from Firecrawl.

Notes

There is currently no chat UI included in this repository.
The app returns vector DB matches by default and only uses Firecrawl when local results are empty.
If you want stronger fallback behavior, the query_with_fallback logic can be updated to use a similarity threshold.

Available Tools

3 tools

query_ragD

Query the RAG knowledge base

ParametersJSON Schema

Name	Required	Description	Default
`k`	No
`query`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

D1.9/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must disclose behavioral traits, but it only states 'Query the RAG knowledge base'. It does not mention that the operation is read-only, any side effects, authentication needs, or rate limits. The description adds no behavioral context beyond the name.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise (one sentence) but under-specified. While it is front-loaded, it fails to provide necessary information, making it a tautology of the tool name. Conciseness without substance is not beneficial.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has an output schema, return values are not needed, but the description lacks context on when to use this tool, parameter semantics, and how it differs from siblings. It is incomplete for an agent to correctly select and invoke it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description does not explain any parameters. The 'query' and 'k' parameters are not described at all, leaving the agent to infer their meaning from names alone. The default for k (5) is in the schema but not clarified as the number of results.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Query the RAG knowledge base' provides a clear verb and resource, but it is generic and does not distinguish from the sibling 'query_rag_with_fallback'. It lacks specificity about the query type (e.g., semantic search).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is given on when to use this tool versus alternatives like 'query_rag_with_fallback' or 'seed_faq'. There are no usage conditions, when-not, or contexts provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

query_rag_with_fallbackC

Query the RAG knowledge base with web fallback

ParametersJSON Schema

Name	Required	Description	Default
`k`	No
`query`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

C2.7/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses web fallback behavior but lacks details on fallback conditions, latency, or side effects. No annotations provided.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Very concise (one sentence), but at the expense of omitting necessary parameter details and usage context.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Minimal description for a tool with fallback behavior and two undocumented parameters; output schema reduces need for return value explanation but parameter semantics missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and description provides no explanation for 'query' or 'k' parameters, leaving agent uninformed about their roles.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool queries the RAG knowledge base with web fallback, but does not explicitly distinguish from sibling 'query_rag' which likely lacks fallback.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool over siblings 'query_rag' or 'seed_faq', and no mention of circumstances for web fallback triggering.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

seed_faqA

Seed the knowledge base with the ML FAQ dataset

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A3.5/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided. The description only states the action without disclosing behavioral traits like destructive potential (overwrites existing data?), idempotency, or required permissions. For a seed operation, such details are critical.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, no wasted words. Front-loaded with action and resource. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given complexity is low (no parameters, simple action) and output schema exists, the description is mostly adequate but lacks information on idempotency, error states, and whether seeding is cumulative or replaces. Agent may need to infer or test.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters in schema, so description adds no parameter info. Baseline for 0-parameter tools is 4, and the description sufficiently covers the tool's purpose. No additional parameter details needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Seed') and the resource ('knowledge base') with a specific dataset ('ML FAQ dataset'). It distinguishes from sibling query tools (query_rag, query_rag_with_fallback) by implying this is an initialization step.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool vs alternatives. No mention of prerequisites, idempotency, or whether it should be run once or on updates. Sibling tools are query-focused but no explicit comparison.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

3 tool updatesv0.1.0Jul 30, 2026
- First observedquery_rag
- First observedquery_rag_with_fallback
- First observedseed_faq

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

C2.7/5.0

Scored 2026-07-30 05:30 across 3 tools

Disambiguation4/5

The two query tools are distinguished by the fallback feature, and seed is clearly separate. Some confusion possible but descriptions help.

Naming Consistency5/5

All tools follow a consistent snake_case verb_noun pattern, making naming predictable and logical.

Tool Count3/5

With only 3 tools, the set feels minimal but is within acceptable bounds for a simple RAG server. However, missing management tools make it slightly thin.

Completeness2/5

The toolset lacks capabilities to update, delete, or list documents, which are essential for a complete RAG knowledge base management. This is a significant gap.

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

MESSORA A
dev.messora
Scrape, crawl and search the web for AI agents via MCP.
Web Scraping Browser Automation Search
51
Frenchie A
io.github.Lab94
OCR, transcription, file extraction, and image generation for AI agents via MCP.
AI & Machine Learning Image & Video Processing Speech Processing
72
ctx A
io.github.vanshulgoyal101
Turn a GitHub repo or docs site into agent-ready context: pack it or search it, over MCP.
RAG Systems Search Documentation Access
611
DocsMint B
io.github.HiAi-gg
Cloud or self-hosted knowledge for AI agents: hybrid search, reranking, GraphRAG, scoped MCP tools.
Documentation Access Knowledge & Memory RAG Systems
17171

Related MCP Servers

RAG MCP Server
RAG Systems Vector Databases
alejandro-ao
F
license
Not graded
quality
D
maintenance
Provides tools for ingesting documents into a local vector database and retrieving relevant information via semantic search, enabling retrieval-augmented generation for MCP clients.
Updated 10 months ago (2025-11-20 15:13 UTC)
6
-
RAG MCP Server
RAG Systems Vector Databases
arbaz-builds
F
license
Not graded
quality
B
maintenance
Exposes a Retrieval-Augmented Generation pipeline as MCP tools, allowing users to index documents and query them through any MCP-compatible client like Claude or IDEs.
Updated 2 months ago (2026-07-22 04:11 UTC)
-
dryad-rag-mcpofficial
RAG Systems Search
DryadAI
A
license
A
quality
C
maintenance
Exposes a RAG document-search API as MCP tools (rag_health, rag_ingest, rag_query), enabling agents to index and search markdown documents with cited results through natural language.
Updated a month ago (2026-08-07 04:11 UTC)
3
MIT
reed-mcp
RAG Systems Search
Ulzuhan
A
license
A
quality
A
maintenance
Provides read-only MCP tools for searching and asking over private documents via a local RAG service (reed), returning ranked passages with citations while keeping data on the machine.
Updated a month ago (2026-08-11 14:56 UTC)
4
Apache 2.0

Agentic RAG MCP

What this project does

Repository structure

Setup for a new user

1. Clone the repository

2. Create a Python virtual environment

3. Install dependencies

4. Create environment variables

5. Run the FastAPI backend

6. Run the MCP server

How to use

Ingest documents

Query local vector store

Query with fallback to Firecrawl

Notes

Available Tools

Output Schema

TDQS

Output Schema

TDQS

Output Schema

TDQS

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

RAG MCP Server

RAG MCP Server

dryad-rag-mcpofficial

reed-mcp