# shreyasgaikwad-04/mcp-based-financial-research-agent architecture

> Architecture diagram of the GitHub repository shreyasgaikwad-04/mcp-based-financial-research-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shreyasgaikwad-04/mcp-based-financial-research-agent
- Repository: https://github.com/shreyasgaikwad-04/mcp-based-financial-research-agent

## Overview

This is a compact financial-research assistant: users ask company or market questions through Streamlit or the FastAPI endpoint, and the LangGraph workflow plans tool calls, gathers financial/news evidence, checks coverage, and produces a grounded answer with sources. The MCP client connects to a reusable MCP server, which dispatches market, fundamentals, and news tools. The README documents Yahoo Finance, Tavily, and optional Langfuse; sampled tool code confirms Yahoo Finance and Tavily use, while tracing wiring is not shown, so it is omitted. Workflow detail is based on partial excerpts.

Main entry points: [`app/graph.py`](https://github.com/shreyasgaikwad-04/mcp-based-financial-research-agent/blob/main/app/graph.py) (LangGraph workflow), [`mcp_server/server.py`](https://github.com/shreyasgaikwad-04/mcp-based-financial-research-agent/blob/main/mcp_server/server.py) (MCP server), [`app/main.py`](https://github.com/shreyasgaikwad-04/mcp-based-financial-research-agent/blob/main/app/main.py) (FastAPI API), [`ui/streamlit_app.py`](https://github.com/shreyasgaikwad-04/mcp-based-financial-research-agent/blob/main/ui/streamlit_app.py) (Streamlit UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_streamlit["Streamlit UI<br/>[streamlit_app.py]"]
  node_api["FastAPI API<br/>[main.py]"]
  node_answer["Answer and sources"]
end

subgraph group_workflow["Research workflow"]
  node_workflow["LangGraph workflow<br/>[graph.py]"]
  node_planner["Research planner<br/>[graph.py]"]
  node_research["Research executor<br/>[graph.py]"]
  node_aggregate["Evidence aggregation<br/>[graph.py]"]
  node_verify["Evidence verification<br/>[graph.py]"]
  node_writer["Grounded answer<br/>[graph.py]"]
end

subgraph group_mcp["MCP tool layer"]
  node_mcp_client["MCP client<br/>[mcp_client.py]"]
  node_mcp_server["MCP server<br/>[server.py]"]
  node_market_tools["Market tools<br/>[market.py]"]
  node_fundamentals_tools["Fundamentals tools<br/>[fundamentals.py]"]
  node_news_tool["News search<br/>[research.py]"]
end

subgraph group_integrations["External data and AI"]
  node_yahoo["Yahoo Finance"]
  node_tavily["Tavily"]
  node_openai["OpenAI model"]
end

node_user(("Research user"))

node_user -->|"asks question"| node_streamlit
node_streamlit -->|"runs research"| node_workflow
node_workflow -->|"returns answer"| node_streamlit
node_user -->|"submits question"| node_api
node_api -->|"runs research"| node_workflow
node_api -->|"returns response"| node_answer
node_workflow -->|"starts at"| node_planner
node_planner -->|"lists tools"| node_mcp_client
node_planner -.->|"plans with"| node_openai
node_planner -->|"dispatches plan"| node_research
node_research -->|"calls tools"| node_mcp_client
node_mcp_client -->|"MCP requests"| node_mcp_server
node_mcp_server -->|"dispatches market"| node_market_tools
node_mcp_server -->|"dispatches fundamentals"| node_fundamentals_tools
node_mcp_server -->|"dispatches news"| node_news_tool
node_market_tools -->|"fetches market data"| node_yahoo
node_fundamentals_tools -->|"fetches financials"| node_yahoo
node_news_tool -->|"searches news"| node_tavily
node_research -->|"passes tool results"| node_aggregate
node_aggregate -->|"passes evidence"| node_verify
node_verify -->|"requests more research"| node_research
node_verify -->|"sufficient evidence"| node_writer
node_writer -.->|"writes with"| node_openai
node_writer -->|"returns answer"| node_answer
node_writer -->|"updates final state"| node_workflow

click node_streamlit "https://github.com/shreyasgaikwad-04/mcp-based-financial-research-agent/blob/main/ui/streamlit_app.py"
click node_api "https://github.com/shreyasgaikwad-04/mcp-based-financial-research-agent/blob/main/app/main.py"
click node_workflow "https://github.com/shreyasgaikwad-04/mcp-based-financial-research-agent/blob/main/app/graph.py"
click node_planner "https://github.com/shreyasgaikwad-04/mcp-based-financial-research-agent/blob/main/app/graph.py"
click node_research "https://github.com/shreyasgaikwad-04/mcp-based-financial-research-agent/blob/main/app/graph.py"
click node_aggregate "https://github.com/shreyasgaikwad-04/mcp-based-financial-research-agent/blob/main/app/graph.py"
click node_verify "https://github.com/shreyasgaikwad-04/mcp-based-financial-research-agent/blob/main/app/graph.py"
click node_writer "https://github.com/shreyasgaikwad-04/mcp-based-financial-research-agent/blob/main/app/graph.py"
click node_mcp_client "https://github.com/shreyasgaikwad-04/mcp-based-financial-research-agent/blob/main/app/mcp_client.py"
click node_mcp_server "https://github.com/shreyasgaikwad-04/mcp-based-financial-research-agent/blob/main/mcp_server/server.py"
click node_market_tools "https://github.com/shreyasgaikwad-04/mcp-based-financial-research-agent/blob/main/mcp_server/tools/market.py"
click node_fundamentals_tools "https://github.com/shreyasgaikwad-04/mcp-based-financial-research-agent/blob/main/mcp_server/tools/fundamentals.py"
click node_news_tool "https://github.com/shreyasgaikwad-04/mcp-based-financial-research-agent/blob/main/mcp_server/tools/research.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_streamlit,node_api,node_answer,node_user toneBlue
class node_workflow,node_planner,node_research,node_aggregate,node_verify,node_writer toneAmber
class node_mcp_client,node_mcp_server,node_market_tools,node_fundamentals_tools,node_news_tool toneMint
class node_yahoo,node_tavily,node_openai toneRose
```

## Components

### User interfaces

- [Streamlit UI](https://github.com/shreyasgaikwad-04/mcp-based-financial-research-agent/blob/main/ui/streamlit_app.py): `ui/streamlit_app.py`
- [FastAPI API](https://github.com/shreyasgaikwad-04/mcp-based-financial-research-agent/blob/main/app/main.py): `app/main.py`
- **Answer and sources**

### Research workflow

- [LangGraph workflow](https://github.com/shreyasgaikwad-04/mcp-based-financial-research-agent/blob/main/app/graph.py): `app/graph.py`
- [Research planner](https://github.com/shreyasgaikwad-04/mcp-based-financial-research-agent/blob/main/app/graph.py): `app/graph.py`
- [Research executor](https://github.com/shreyasgaikwad-04/mcp-based-financial-research-agent/blob/main/app/graph.py): `app/graph.py`
- [Evidence aggregation](https://github.com/shreyasgaikwad-04/mcp-based-financial-research-agent/blob/main/app/graph.py): `app/graph.py`
- [Evidence verification](https://github.com/shreyasgaikwad-04/mcp-based-financial-research-agent/blob/main/app/graph.py): `app/graph.py`
- [Grounded answer](https://github.com/shreyasgaikwad-04/mcp-based-financial-research-agent/blob/main/app/graph.py): `app/graph.py`

### MCP tool layer

- [MCP client](https://github.com/shreyasgaikwad-04/mcp-based-financial-research-agent/blob/main/app/mcp_client.py): `app/mcp_client.py`
- [MCP server](https://github.com/shreyasgaikwad-04/mcp-based-financial-research-agent/blob/main/mcp_server/server.py): `mcp_server/server.py`
- [Market tools](https://github.com/shreyasgaikwad-04/mcp-based-financial-research-agent/blob/main/mcp_server/tools/market.py): `mcp_server/tools/market.py`
- [Fundamentals tools](https://github.com/shreyasgaikwad-04/mcp-based-financial-research-agent/blob/main/mcp_server/tools/fundamentals.py): `mcp_server/tools/fundamentals.py`
- [News search](https://github.com/shreyasgaikwad-04/mcp-based-financial-research-agent/blob/main/mcp_server/tools/research.py): `mcp_server/tools/research.py`

### External data and AI

- **Yahoo Finance**
- **Tavily**
- **OpenAI model**

### Other components

- **Research user**

## Connections

- Research user → Streamlit UI: asks question
- Streamlit UI → LangGraph workflow: runs research
- LangGraph workflow → Streamlit UI: returns answer
- Research user → FastAPI API: submits question
- FastAPI API → LangGraph workflow: runs research
- FastAPI API → Answer and sources: returns response
- LangGraph workflow → Research planner: starts at
- Research planner → MCP client: lists tools
- Research planner → OpenAI model: plans with
- Research planner → Research executor: dispatches plan
- Research executor → MCP client: calls tools
- MCP client → MCP server: MCP requests
- MCP server → Market tools: dispatches market
- MCP server → Fundamentals tools: dispatches fundamentals
- MCP server → News search: dispatches news
- Market tools → Yahoo Finance: fetches market data
- Fundamentals tools → Yahoo Finance: fetches financials
- News search → Tavily: searches news
- Research executor → Evidence aggregation: passes tool results
- Evidence aggregation → Evidence verification: passes evidence
- Evidence verification → Research executor: requests more research
- Evidence verification → Grounded answer: sufficient evidence
- Grounded answer → OpenAI model: writes with
- Grounded answer → Answer and sources: returns answer
- Grounded answer → LangGraph workflow: updates final state