# Financial AI Agent

> Six-service financial AI proof of concept with FastAPI, MCP, RAG, PostgreSQL, React, Ollama, and Docker.

- **Type:** MCP server
- **Install:** `agentstack add mcp-snaetwarre-financial-ai-agent`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [SnaetWarre](https://agentstack.voostack.com/s/snaetwarre)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [SnaetWarre](https://github.com/SnaetWarre)
- **Source:** https://github.com/SnaetWarre/Financial_AI_Agent
- **Website:** https://snaetwarre.github.io/My-Portofolio/work/financial-agent.html

## Install

```sh
agentstack add mcp-snaetwarre-financial-ai-agent
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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.

```bash
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

```bash
# 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](https://snaetwarre.github.io/My-Portofolio/work/financial-agent.html)
- [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](https://github.com/SnaetWarre)
- **Source:** [SnaetWarre/Financial_AI_Agent](https://github.com/SnaetWarre/Financial_AI_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.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-snaetwarre-financial-ai-agent
- Seller: https://agentstack.voostack.com/s/snaetwarre
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.