FinRAG-MCP Server

FinRAG-MCP is a Role-Based Access Control (RBAC) Retrieval-Augmented Generation (RAG) server integrated with the Model Context Protocol (MCP). It lets you securely query company documents (Engineering, Finance, HR, Marketing, General) where each user role only sees what they are allowed to access, and it provides sources and citations for every answer.

How to use

You interact with FinRAG-MCP through an MCP client to perform role-aware queries against your document set. Set the role for your session, then issue natural language questions or searches. The system returns answers along with the relevant file chunks and sources, keeping sensitive data restricted by your role.

Typical usage patterns include:

• Set your role to FINANCE, then query for revenue-related insights.
• As a manager, broaden your query to summarize departmental performance while preserving RBAC boundaries.
• Ask for specific sources or citations to verify each answer.

Example command flow you would perform from an MCP client:

• Define your role for the session (e.g., set_role("FINANCE")).
• Run a search or ask a question (e.g., search("Q4 2024 revenue drivers", top_k=5)).
• Review the generated answer with included sources and file chunks.

How to install

# Prerequisites
# - Python with venv support
# - MCP client available (Claude MCP or compatible)
# - Access to the FinRAG-MCP project files

# Clone the project
git clone https://github.com/YOUR_GITHUB/finrag-mcp.git
cd finrag-mcp

# Create and activate a Python virtual environment (using uvx tooling)
uv venv .venv
source .venv/bin/activate

# Synchronize MCP tooling and environment
uv sync

# Create environment file with required keys
cat > env/.env << 'EOF'
OPENAI_API_KEY=sk-REPLACE_ME
OPENAI_MODEL=gpt-4o-mini
EMBED_MODEL=text-embedding-3-large
QDRANT_LOCAL_PATH=.qdrant_local
QDRANT_COLLECTION_PREFIX=finrag
FINRAG_ROLE=EMPLOYEE
EOF

# Ingest documents (optional step depending on data sources)
uv run python -m ingest.run_ingest --data-root ./data

Note: After setup, you will run the MCP server, a gateway, and an optional UI to interact with FinRAG-MCP.

Start the MCP server and gateway as shown below, then connect via your MCP client.

## Configuration and usage notes

MCP server is run locally as a stdio process using the Python runtime in your virtual environment. You provide environment variables that configure access to the OpenAI model, embedding model, and local vector store. The key variables are:
- OPENAI\_API\_KEY: Your API key for the language model
- OPENAI\_MODEL: The model you want to use
- EMBED\_MODEL: The embedding model for vector search
- QDRANT\_LOCAL\_PATH: Local path to the Qdrant store
- QDRANT\_COLLECTION\_PREFIX: Prefix for your Qdrant collections
- FINRAG\_ROLE: Your current role (e.g., EMPLOYEE, FINANCE, HR, etc.)

The local MCP server command to run is exposed as a stdio entry with a direct path into the virtual environment. You will configure your MCP client to invoke this command so Claude MCP can call the tool directly.

## Example MCP server config (stdio)

{ "mcpServers": { "finrag_mcp": { "type": "stdio", "name": "finrag_mcp", "command": "<path-to-project>/finrag-mcp/.venv/bin/python", "args": ["-m", "mcp_server.server"], "env": [ {"name": "OPENAI_API_KEY", "value": "sk-REPLACE_ME"}, {"name": "OPENAI_MODEL", "value": "gpt-4o-mini"}, {"name": "EMBED_MODEL", "value": "text-embedding-3-large"}, {"name": "QDRANT_LOCAL_PATH", "value": ".qdrant_local"}, {"name": "QDRANT_COLLECTION_PREFIX", "value": "finrag"}, {"name": "FINRAG_ROLE", "value": "EMPLOYEE"} ] } } }

## Security and RBAC considerations

Access is controlled by roles so that each user only retrieves information they are permitted to view. Responses include sources and file chunks to enable traceability. Treat the MCP API keys and environment as sensitive data and keep them secure in your deployment.

## Troubleshooting

If you encounter connection issues from your MCP client, verify:
- The stdio command path and arguments are correct
- The environment file contains valid OpenAI and embedding model settings
- The local vector store (Qdrant) is accessible at the specified path
- The role you set matches the data access you expect for the query

## Tools available to you

Two core tools you can invoke from the MCP client are:
- set\_role(role): Set the current role for your session to control access boundaries.
- search(query, top\_k): Retrieve relevant document chunks and sources for the given query.

## Available tools

### set\_role

Set the current user role to enforce RBAC during queries.

### search

Query the document collection and return top\_k relevant chunks with sources.