Financial AI Agent

Financial AI Agent

A conversational application for exploring a simulated investment portfolio. It combines streamed LLM responses, retrieval-augmented generation, typed MCP tools, persistent sessions, and explicit trade confirmation in a reproducible six-service architecture.

> This is an academic proof of concept. It uses historical 2024 market data projected onto a 2025 timeline, does not connect to a broker, and is not financial advice.

What the system does

• Streams assistant output and processing events to a React interface with server-sent events.
• Routes requests between general conversation, retrieval, and portfolio actions.
• Exposes seven portfolio and market-data operations through Model Context Protocol tools.
• Stores portfolios, orders, and chat sessions in PostgreSQL.
• Retrieves project knowledge and market context from ChromaDB.
• Converts trade requests into pending actions that require explicit confirmation.
• Runs locally through Docker Compose with Ollama for generation and embeddings.

Architecture

| Service | Responsibility | Technology | Port | | --- | --- | --- | --- | | Frontend | Chat, portfolio state, citations, and processing trace | React, Vite | 3000 | | Inference API | Orchestration, guardrails, SSE, and trade-intent flow | FastAPI | 8081 | | MCP server | Typed portfolio, order, and price tools | FastAPI, FastMCP | 8000 | | RAG pipeline | Ingestion, embeddings, and retrieval | ChromaDB, Ollama | - | | Database | Portfolios, orders, and sessions | PostgreSQL | 5432 | | Local models | Text generation and embeddings | Ollama, Qwen 2.5 | 11434 |

The model never receives direct database access. The inference service decides when a tool is appropriate, the MCP server validates and executes typed operations, and PostgreSQL remains the source of truth.

My contribution

This was a two-person academic project. I owned the backend architecture, agent orchestration, MCP integration, persistence, containerization, tests, and most frontend integration.

Concretely, I:

• built and refined the FastAPI orchestrator, server-sent event protocol, guardrails, and error handling;
• migrated portfolio state from JSON to PostgreSQL and moved executable operations behind FastMCP;
• implemented the pending-order and confirmation flow so generated text cannot silently mutate the portfolio;
• integrated RAG queries, citations, MCP tool-call visibility, and persistent sessions;
• containerized the full stack and added health checks and persistent volumes;
• added focused tests around guardrails, price lookup, order execution, persistence, and confirmation.

Run locally

Requirements: Docker with Compose, at least 8 GB RAM, and enough disk space for the Ollama models.

git clone https://github.com/SnaetWarre/Financial_AI_Agent.git
cd Financial_AI_Agent
cp .env.example .env
docker compose up --build

Then open:

• frontend: http://localhost:3000
• inference API docs: http://localhost:8081/docs
• MCP health endpoint: http://localhost:8000/health

The first start is slower because Ollama downloads the configured models and the RAG service builds its index.

Verification

# Static Python validation used in CI
python -m compileall inference mcp-server rag-pipeline shared

# Frontend production build
npm --prefix frontend ci
npm --prefix frontend run build

# Service-level tests, after the required services are available
pytest inference/tests
pytest mcp-server/tests

Supported simulated assets

SPY, GLD, SLV, AGG, TLT, and VNQ.

Limitations and production considerations

• Prices are projected historical data, not a live market feed.
• The application simulates trading and has no broker integration.
• A production version would need authenticated users, authorization boundaries, encrypted secrets, audit logging, rate limits, model and retrieval monitoring, live-data licensing, and human-reviewed financial compliance.
• Generated answers remain probabilistic; confirmation and typed tools reduce risk but do not make model output authoritative.

Further reading

• Architecture and engineering case study
• [Project report](REPORT.pdf)

License

MIT

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: SnaetWarre
• Source: SnaetWarre/FinancialAI_Agent
• License: MIT
• Homepage: https://snaetwarre.github.io/My-Portofolio/work/financial-agent.html

Install and usage instructions live in the source repository linked above.