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.

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.