flexreport-mcp

A standalone MCP microservice that exposes the FlexReport
equity backend's live events, research-report artifacts, and database of
750M+ datapoints as on-demand tools for Claude (and any MCP client).

It supercharges AI agents with real-time market events and curated, golden-source
data spanning fundamentals, transcripts, filings, insider trades (Forms 3, 4, and 5),
ratios, macro data, IR decks pulled straight from each company's investor relations
site, and more.

Quick Install

Add the connector to Claude Code

claude mcp add --transport http flexreport https://mcp.flexreportfinapi.com/mcp

Or add to Codex

codex mcp add flexreport --url https://mcp.flexreportfinapi.com/mcp

Then start Claude and just ask (e.g. "pull the biggest movers from flexreport").
On the first data call your MCP client runs an OAuth sign-in in your browser —
sign in or register when prompted; you never paste a token. Add --scope user to
make it available in every directory. See Auth for details.

Demo

Stream real-time events in the terminal. Ask Claude to watch the market and
events arrive as they land: movers, earnings releases, 8-Ks, IR decks and fresh
report plans. As each report plan saves, Claude renders the refreshed report.

"Look out for the biggest movers, earnings releases, transcript updates, investor
decks, and 8K releases post market close, streaming these as they happen with Flexreport"

"For every thing that comes, can you check if the latest report plan is available,
to pull a refreshed report to provide deeper context"

Open the research report. Every figure links back to the query that produced
it, and every headline links to its source. Here's a report for AAPL:

"Get me the latest flexreport report for AAPL"

Open the full AAPL report (PDF, 13 pages)

Use-cases

1. Real-time

1a. Streaming (events and real-time reports). Subscribe to events as they publish, including the report_plan topic, which fires each time a report is ready, then pull the rendered report: "Subscribe me to earnings releases, 8-Ks, IR publications and new report plans for NVDA, AVGO, AMD and MU. As each one lands, tell me what happened, check the intraday tape for an abnormal move, and pull the FlexReport report once it's ready."

Tools: register_event_subscription → stream_event_subscription, or ad-hoc stream_events, then detect_intraday_outlier_jumps and get_latest_report.

1b. Events from the past twelve hours. Analyze real-time SEC 8-K filings, while also pulling in investor relations decks and 5-minute bars to quickly identify stocks making meaningful moves: "What are the latest 8-K releases? Highlight the most significant ones, pull the accompanying investor relations releases via FlexReport, chart 5-minute bars for any names making meaningful moves, and tell me how they align with each company's current state. I would like this in tabular format: 8-K summary, company trend, FlexReport 8-K analysis S3 link, IR deck link."

Tools: situate → list_realtime_events, then get_aftermarket_data / detect_intraday_outlier_jumps and get_latest_report.

2. Reports

2a. The latest report for a specific company: "Pull the latest FlexReport report on Snowflake and summarize what changed this quarter: guidance, margins, and anything management flagged on the call."

Tools: get_latest_report(["SNOW"]). A fresh plan renders in ~10-20 s; a stale or missing symbol can be rebuilt with generate_report_for_stock.

2b. The latest reports for a time period: "What reports have come out in the Energy sector over the past three days? Pull the fresh ones and rank them by how significant the underlying event was."

Tools: list_available_reports(report_date=<3 days ago>), filtered to Energy names (list_options("sectors"), get_company_snapshot), then get_latest_report for the fresh ones.

2c. A bespoke report built on your criteria: "Build me a report on large-cap US semiconductors with ROIC above 20% and net debt/EBITDA under 1x, trading above their 200-day SMA with RSI below 60. Show the fundamentals, the technicals and the latest estimate revisions for each, laid out in my saved template."

Tools: screen_stocks, explore_data_catalogue (ratios, fundamentals, estimates), get_technical_indicator_data, and get_user_template. The agent assembles the PDF in your template; set one up with draft_user_template → save_user_template.

3. Predictive analytics

Predict upcoming earnings volatility, pulling in simple and exponential moving averages and Bollinger Bands, and creating a bespoke investment memo: "Predict tomorrow's upcoming earnings volatility, highlighting the stocks slated for the biggest moves; chart their simple and exponential moving averages and Bollinger Bands; and highlight the biggest fundamental drivers right now, putting this all in an investment memo for my team."

Tools: list_earnings_announcements → predict_earnings_move, get_technical_indicator_data, get_company_snapshot.

4. Research and exploration

Run thematic research on a market narrative: "The AI trade has cooled recently, largely due to CapEx concerns and return on investment. I believe this has happened before, in the fall of 2025. Can you confirm, and what were the factors that allayed those concerns? Was it management commentary, continued demand for AI services, robust profitability and higher guidance? Please put together an in-depth report with FlexReport Finance."

Tools: explore_data_catalogue (transcripts, fundamentals, estimates), trace_data_sources / get_document_section for cited quotes, or generate_research_report for the full write-up.

Tools

50 tools, grouped by the module that registers them. Clients see them in tools/__init__.py import order (situate first).

Situate & real-time events (tools/realtime_events.py)

Event streaming (tools/event_subscriptions.py)

Reports & PDF templates (tools/pdf_reports.py)

Data exploration, citations & saved queries (tools/data_exploration.py)

Market data (tools/market_data.py)

Screening, portfolios & strategies (tools/strategies.py)

Scheduling (tools/scheduling.py)

Utility & billing (tools/utility.py)

For a single named company, get_company_snapshot and get_company_event_web are the standard pair — the two halves of the same question, usually called together. The snapshot is the what (where the company stands now: thesis, fundamentals, technicals, ownership, grades); the event web is the why (the episode behind it: earnings print → 8-K → transcript update → IR publication → analyst reaction, with edges saying how each relates). A snapshot on its own is a verdict with no evidence; the web is the evidence. The web is also the cheap grounding call that makes the rest of the loop precise — each node carries the exact follow-up call, so the next list_realtime_events, explore_data_catalogue, or report request carries real event types and dates instead of guessed ones.

Typical agent loop: default to explore_data_catalogue(query) for open-ended/exploratory questions (fast, interactive charts/tables). Escalate only on a crystal-clear intent — get_latest_report(symbols) for the existing report on a named ticker, screen_stocks(...) to filter the universe, or generate_research_report(query) for an explicit deep dive (~10-12 min, async — poll with get_task_status).

Asked the same question twice — or the same question about a different company? explore_data_catalogue re-plans its SQL every time, so once an exploration is done the agent offers to save it: save_user_query stores its query_tokens, and the backend authors a placeholder twin of each query — lifting the ticker, CIK list, date, interval, and count into typed slots — alongside the row's metadata, which names those slots and summarises what the row asks. run_saved_query then replays the row's queries exactly (the same queries against live data, in seconds, no planning step, no polling), or takes the row's query_placeholder tokens plus typed values to re-aim the request at other entities — "TGT's last 8 quarters of sales" saved yesterday answers "KSS's last 8 quarters of sales" today, deterministically and with no language model in the fill, the substituted parameters (and any defaulted_parameters / ignored_values) returned beside the rows; a prompt still covers what the agent cannot type. list_saved_queries is the thing to check before any exploration, matching the question against each row's metadata — summary, parameters, datasets — rather than its user_request label, and skipping rows marked stale; delete_saved_query clears one out. Pass max_rows on every replay, and pick the queries to run from metadata.result_schema so the _constituents companion (7,000–35,000 rows) stays out of the call. The tokens are opaque ciphertext the backend minted: pass them through unchanged, never construct or edit one, and never show one to the user.

Want reports in your own format? A user supplies an HTML page — masthead, colours, layout, branding — and it is saved as a blueprint: the author's stylesheet and page chrome plus one markup pattern per content kind, which the backend applies automatically to every PDF it renders for that user (get_latest_report renders of fresh plans, generate_report_for_stock rebuilds, standard and custom, and scheduled reports). A template is structure and style applied to the document's own content: nobody fills template markup, and no other call changes. It is a visual choice, so it is approved by looking: draft_user_template compiles the page under several treatments and renders each as PNG previews of the platform's specimen document (an add_on restyles one section of the standard layout, named by anchor; a bespoke drives the whole document), the user picks one, and save_user_template(draft_id, variant_id) stores that treatment — one template per user, upserted. update_user_template changes any field later, or recompiles the stored design when called with no arguments; get_user_template shows what is in force; delete_user_template returns the user to the standard layouts.

There is no agent-driven PDF builder: the build_pdf_full_width / build_pdf_sidebar tools (backend /create-pdf and /create-pdf-sidebar) and the pdf_options catalogue were retired in favour of templates. When a user wants a document composed from Flexreport data that no backend report covers — including a bespoke take on a company report ("the SNOW report, built around product revenue and RPO") — the agent explores the items they named, ideates with them over the result sets, and builds the PDF with its own document tooling, overlaying the agreed results in the user's saved template (get_user_template) when one exists — and offering to draft one (draft → preview → save, then update) when none does.

Reports are on-demand: nothing regenerates until someone asks. The two report endpoints are strictly separate:

• get_latest_report → /get-cached-reports is the fast path. A saved report plan is JSON — brief, queries, results, format map — built the moment a material event publishes for a symbol (or by a rebuild) and refreshed nightly while its inputs keep changing. When a symbol's plan is fresh (has a format map, under 7 days old, not older than the symbol's latest report inputs, reads the right side of the EDGAR/FMP split), the endpoint does not return a pre-built PDF: it renders that plan into the user's template in ~10-20 s and lists the symbol under rendering with a task_id to poll. Every other symbol comes back as its cached PDF tagged stale (true = the plan itself is out of date — a print, a filing, a 13F refresh landed after it) or lands in missing.
• generate_report_for_stock → /create-full-report is a full rebuild (~10 min), used sparingly. The agent calls it with the ticker alone only when get_latest_report returned the symbol stale or missing and the user wants to wait; the rebuilt plan is saved, so later get_latest_report calls render it in seconds. Never for a symbol in rendering, and never fanned out across a list.
• Bespoke requests go through exploration, not a rebuild. The agent explores the items the user named (list_saved_queries, then explore_data_catalogue), ideates with them over the result sets, and overlays the agreed results into their template (get_user_template) with its own document tooling.

list_available_reports(event_types, report_date) is the inventory of those saved plans, scoped to plans built on or after report_date (default today) — which symbols have real-time research ready and whether each is fresh (get_latest_report renders it in seconds) or would rebuild (minutes) — so the agent can go from list_realtime_events (an event published) to a fresh report without guessing, or skip the events step and list what is available outright. For "pull the most relevant reports today" the events are the filter and the plans are the availability check, in that order: pull the material types (transcript_update, 8k_release, ir_publication, eps_release, financials_release) and the tape (biggest_mover, biggest_loser), read the content, confirm significance against intraday price action (detect_intraday_outlier_jumps), match the survivors to plans with list_available_reports(event_types=[...]), and pull only those with get_latest_report. situate surfaces this as a suggestion on every market-wide plan, carrying report_date when the 12h realtime window opened on an earlier UTC date. Only an explicit ask for the pipeline's own report rebuilt around named items makes it a custom report — user_override=true plus the shaping lists (financial_items, ratios, as_reported_financial_items, revenue_segment, technical_analysis_items, estimate_items, institutional_ownership CIKs, include_as_report_financials / as_reported_periods) — which is a full build (~10 min) that is never saved. The backend rejects shaping lists without the switch (422), so the tool sets it whenever a shaping field is non-empty. Vocabularies come from list_options: financial_items, financial_ratios, technical_indicators, and the ticker-scoped as_reported_items / revenue_segments and the q-scoped institutional_managers (returns CIKs). Event context is server-owned — the request carries no thesis, change-summary, include_*, or price-date fields.

Code layout

server.py            entrypoint: imports the tools package, adds /health, runs the transport
core.py              the FastMCP instance, server instructions and `_send` (backend forwarding)
client.py            shared httpx client + inbound-bearer forwarding
auth_verifier.py     OAuth resource-server token validation (RS256 via the backend JWKS)
situate.py           pure composition logic behind the `situate` tool
instructions.json    server instructions (non-code copy)
tools/
  realtime_events.py     situate, list_realtime_events, company snapshot / event web, event ontology
  event_subscriptions.py stream_events, register / stream / delete_event_subscription (SSE bounded reads)
  pdf_reports.py         get_latest_report, list_available_reports, generate_*, download_pdf_from_url, PDF templates
  data_exploration.py    explore_data_*, signed drilldowns, trace_data_sources, document sections, saved queries
  utility.py             get_task_status, list_options, list_sub_industries, onboard_symbol, billing
  market_data.py         technical indicators, intraday outliers, after-hours bars, earnings calendar + move prediction, market status
  strategies.py          screen_stocks, portfolio optimization, stock picks, strategy track records
  scheduling.py          schedule / list / delete scheduled tasks

Each module does from core import mcp, _send and registers with @mcp.tool(...);
importing tools registers everything. tools/__init__.py fixes the import order,
which is the order tools are advertised to clients (situate first).

Run locally

python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env          # set API_BASE_URL, MCP_HOST, MCP_PORT
set -a && source .env && set +a
python server.py              # serves streamable-http on http://MCP_HOST:MCP_PORT/mcp

Auth

The server is an OAuth 2.0 Resource Server and stateless (load-balancer
friendly), so auth rides each call. It holds no credentials and no signing
secret — it validates the inbound bearer token and forwards it to the backend,
which enforces scope, plan, and quota.

How it works

Sign-in is a standard browser authorization-code + PKCE flow, run by your MCP
client (e.g. Claude) against the FlexReport backend, which is the Authorization
Server. Register or sign in with an email + password, or use Google
Sign-In — you never paste or type a token:

1. On a request without a valid token the server returns 401 with a
   WWW-Authenticate challenge and serves Protected Resource Metadata at
   /.well-known/oauth-protected-resource, pointing the client at the backend AS.
2. The client opens your browser; you sign in / consent and it receives an RS256
   access token issued by the backend.
3. The server validates that token on every call — signature via the
   backend's JWKS (RS256 public key) plus aud, iss, and exp — then
   forwards it to the backend. Invalid or expired → a clean 401 and the client
   re-runs the flow.

The server never sees your password and never holds the signing key — it stays a
credential-free proxy. Only valid RS256 OAuth tokens are accepted; there is no
password or static-JWT fallback.

Config (env)

Static header

Configure Authorization: Bearer <OAuth access token> in your MCP client and the
server validates and forwards it like any other call — useful for testing with a
token minted elsewhere. Nothing is stored at rest; tokens are forwarded per-call.

Wire into an MCP client

.mcp.json (Claude Code):

{
  "mcpServers": {
    "flexreport": {
      "type": "http",
      "url": "http://localhost:8000/mcp",
      "headers": { "Authorization": "Bearer <YOUR_OAUTH_ACCESS_TOKEN>" }
    }
  }
}

Verify with MCP Inspector

npx @modelcontextprotocol/inspector
# Connect to http://localhost:8000/mcp with header Authorization: Bearer <OAuth access token>
# Confirm the tools list loads (46 tools), then exercise:
#   list_realtime_events("eps_update")        -> events (or [])
#   get_company_event_web("NVDA")             -> event graph (or an empty/degraded web)
#   get_latest_report(["AAPL"])               -> rendering task_id, cached PDF url, or missing  [named-ticker report; max 100 symbols]
#   list_available_reports(["eps_release"])   -> plans built today with `fresh` flags (or []); report_date="YYYY-MM-DD" widens
#   explore_data_catalogue("MU EPS growth last 8 quarters")  -> task_id  [default exploratory route]
#   get_task_status(task_id)                  -> eventually SUCCESS
# Negative: connect with no/invalid token     -> 401 + WWW-Authenticate challenge

Deploy

Build the image and run it as its own container (e.g. a separate ECS service with
its own task definition), independent of the API and Celery workers. Set
API_BASE_URL to the deployed backend URL.

docker build -t flexreport-mcp .
docker run -p 8000:8000 -e API_BASE_URL=https://flexreportfinapi.com flexreport-mcp

Privacy

FlexReport's privacy policy — what's collected, retention windows, and the
third parties involved — is published at
app.flexreportfinapi.com/privacy
(source: PRIVACY.md).