Multi-Agent Financial Research System with MCP

An auditable financial-research workflow that autonomously plans a bounded investigation, routes a query across specialist agents, invokes typed tools through local or real MCP transport, critiques the evidence, and produces a traceable research brief.

The system combines multi-agent orchestration, typed tool calling, MCP transport, retrieval, live-provider adapters, evaluation, and deterministic fallbacks. It produces research briefs and does not place trades or provide investment advice.

Architecture

CLI / FastAPI / Streamlit
          |
          v
   Supervisor Agent ---- optional Ollama planner
          |
          +-- Market Agent ------ market bars, returns, volatility
          +-- News Agent -------- headlines and lightweight sentiment
          +-- Fundamentals Agent  SEC company facts and reported metrics
          +-- Comparison Agent --- aligned multi-symbol risk comparison
          +-- Research Agent ---- arXiv papers
          +-- Document Agent ---- semantic/vector RAG over local notes
          +-- Risk Agent -------- volatility and maximum drawdown
          |
          v
      Critic Agent ------ evidence and coverage checks
          |
          v
   Synthesis Agent ------ optional Ollama synthesis
          |
          v
 Report + evaluation + trace + optional saved artifacts

Tool path in the recommended runtime:
Agent -> ToolGateway -> MCP stdio client -> MCP server -> tool adapter -> provider

Related MCP server: Stock Research MCP Server

What Is Agentic Here?

The tools fetch or calculate data. The agents decide how that evidence is used:

• The supervisor selects specialist agents from the query.

• The supervisor records a research plan, executes it, inspects coverage, and may request one evidence-recovery pass before stopping.

• Specialists call tools, transform raw results into findings, and state limitations.

• The critic checks fallback usage and missing evidence categories.

• The synthesis agent combines findings into one risk-aware thesis.

• Optional Ollama reasoning can replace deterministic planning and prose while retaining a free fallback.

This is bounded agent autonomy: the workflow can plan and execute research, but it cannot place trades or modify external systems.

Quick Start

Python 3.10 or newer is required.

python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install -e ".[api,ui,market]"

Run a reproducible offline analysis through the real MCP client/server path:

FIN_RESEARCH_LIVE=0 \
FIN_RESEARCH_TOOL_RUNTIME=mcp-stdio \
financial-research-agent "Assess NVDA AI infrastructure risk and research" --save

Inspect machine-readable output and the execution trace:

FIN_RESEARCH_LIVE=0 \
FIN_RESEARCH_TOOL_RUNTIME=mcp-stdio \
financial-research-agent "Assess NVDA AI infrastructure risk and research" --json --trace

Saved runs contain report.md, report.json, and trace.json under runs/<run_id>/. The directory is intentionally ignored by Git.

Interfaces

CLI:

financial-research-agent "Assess AMD competition and downside risk"

API:

financial-research-api

Then use GET /health, GET /tools, or POST /research with:

{"query": "Assess NVDA AI infrastructure risk"}

Streamlit UI:

set -a
source .env
set +a
financial-research-ui

Open the printed local URL, usually http://localhost:8501. Enter a question in the Research question field and select Run full investigation. The desk shows the thesis and agent findings first, then Evidence & sources, Quality checks, and Execution trace tabs. The sidebar controls live versus offline data, offline fallback, and optional Ollama reasoning.

Standalone MCP server:

financial-research-mcp

Tool Runtime Modes

• local: direct Python calls through the gateway; fastest for unit tests.

• mcp: an in-process compatibility shim with the same gateway shape. It does not cross an MCP transport.

• mcp-stdio: a real MCP client and server subprocess with one persistent session per research run.

Use mcp-stdio when demonstrating MCP. The server returns provider and fallback provenance with live-source results, so traces remain truthful across the protocol boundary.

Data Sources

Default auto behavior attempts free live sources and falls back to bundled deterministic fixtures when enabled:

• Market: yfinance; optional Alpha Vantage, Polygon, or Financial Modeling Prep keys.

• News: Yahoo Finance RSS; optional Finnhub or NewsAPI key.

• Papers: arXiv Atom API.

• Documents: bundled research notes searched by lexical, token-vector, or optional semantic FAISS retrieval.

• Risk: locally calculated log returns, annualized volatility, and maximum drawdown.

• Fundamentals: SEC Company Facts API when live mode is enabled; bundled demo facts offline.

set -a
source .env
set +a
FIN_RESEARCH_MARKET_PROVIDER=alpha_vantage \
financial-research-agent "Assess PLTR earnings risk"

To prevent fallback and fail loudly when a live source is unavailable:

FIN_RESEARCH_OFFLINE_FALLBACK=0 financial-research-agent "Assess NVDA risk"

Optional Local LLM

Deterministic planning and synthesis work without an API or model bill. For free local reasoning, install Ollama separately and run:

ollama pull llama3.2:3b
FIN_RESEARCH_LLM=ollama \
FIN_RESEARCH_OLLAMA_MODEL=llama3.2:3b \
financial-research-agent "Assess NVDA AI infrastructure risk and research"

Ollama can assist supervisor planning, specialist explanations, critique, synthesis, and an optional LLM judge. If it is unavailable, each operation falls back to deterministic logic.

Semantic RAG

The default document tool uses a dependency-free token-vector cosine retriever. Install the larger optional stack to use sentence-transformer embeddings with FAISS nearest-neighbor search:

python3 -m pip install -e ".[rag]"

The bundled documents and evaluation cases are Python package data, so they remain available after wheel installation rather than only from a source checkout.

Evaluation and Verification

python3 -m pip install -e ".[dev,api,market]"
ruff check src tests
python3 -m unittest discover -s tests -v
FIN_RESEARCH_LIVE=0 financial-research-eval
financial-research-eval --ablation --limit 6

The 30-case labelled benchmark reports routing and tool precision/recall, provider success and fallback rates, citation coverage, claim support, contradiction/critic recall, report completeness, MCP failures, and stage-level latency. The ablation command compares deterministic orchestration with the local Ollama model on a stratified sample. See EVALUATION.md for methodology, measured results, and limitations.

The benchmark does not prove investment correctness or alpha. Those require time-aligned datasets, independent expert labels, source-entailment evaluation, and out-of-sample financial validation.

GitHub Actions runs linting, tests, and the offline benchmark on Python 3.10 and 3.12. A Dockerfile packages the FastAPI service.

Project Layout

src/financial_research_agent/
  agents/          supervisor, specialists, comparison, fundamentals, critic, synthesis
  mcp/             MCP tool contracts and stdio server
  tools/           providers, document retrieval, risk calculations
  data/            packaged offline fixtures and benchmark cases
  tool_gateway.py  local/shim/real-MCP runtime boundary
  reasoning.py     deterministic and optional Ollama reasoning
  evaluation.py    report, freshness, contradiction, and grounding diagnostics
  grounding.py     evidence IDs, registry, and thesis citations
  observability.py provider/transport/LLM/stage latency, evidence, failures, fallbacks
  cli.py api.py ui.py
tests/             unit, routing, benchmark, and MCP integration tests

Current Scope

• This is an autonomous research-assistance prototype, not investment advice or execution infrastructure.

• Free sources are delayed, rate-limited, and not exchange-grade.

• Headline sentiment is rule-based; it is not a validated finance-language model.

• The deterministic supervisor uses keyword routing; optional Ollama planning is not guaranteed to be correct.

• Multi-ticker comparison is supported for basic return and volatility context; portfolio optimization is not implemented.

• SEC Company Facts are summarized as reported fundamentals; full filing retrieval and claim-level excerpts are future work.

• The critic detects configured fallback, coverage, and market/news contradiction classes; open-ended claim resolution remains future work.

• Confidence values are engineering heuristics, not calibrated probabilities.

• Offline market/news/paper records are synthetic fixtures and are visibly marked as such.

• “Autonomous” is deliberately bounded: there is no open-ended self-modification, trade execution, or unreviewed external action.

See PRODUCT_READINESS.md for the self-audit and LEARNING_NOTES.md for concept explanations.

License

MIT. See LICENSE.