Flexreport Finance

flexreport-mcp

[smithery badge] [Listed on mcpservers.org]

A standalone MCP microservice that provides access to Flexreport Finance'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"

[Claude Code streaming Flexreport Finance events after the close and rendering reports as their plans land]

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"

[Page 1 of the Flexreport Finance AAPL company deep dive]

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

By default, a live-streaming ask gets a dashboard (in Claude, an Artifact) rather than a chat transcript. The page runs the stream_events loop itself, carrying the cursor from read to read, so one prompt keeps the stream open. If the page can't reach the server, the agent runs the loop and writes each event into the dashboard. Ask for chat output explicitly if you prefer the terminal view shown in the demo above.

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 Finance, 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 Finance 8-K analysis S3 link, IR deck link."

Tools: situate (no symbols) → 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 Finance report on Snowflake and summarize what changed this quarter: guidance, margins, and anything management flagged on the call."

Tools: get_latest_report(["SNOW"]). It returns the latest report in seconds; a stale or missing symbol can get a new note from generate_report_for_stock (a few minutes).

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

57 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)

Default delivery for a live-streaming ask is a dashboard (in Claude, an Artifact) whose page loops stream_events with its cursor. The server instructions and the stream tools' docstrings both say so.

Reports & PDF templates (tools/pdf_reports.py)

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

Market data (tools/market_data.py)

Data feeds (tools/data_feeds.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 report written for that user (each event-time report gets a copy in their template, which get_latest_report serves as template: "user", 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 Finance 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 written at event time: each material event publishes a new report for the symbol, announced on the stream-only report_plan topic. The two report endpoints are strictly separate:

• get_latest_report → /get-cached-reports is the fast path, and fetch-only. A material event publishing for a symbol saves a report plan (JSON — brief, queries, results, format map) and writes the symbol's report from it within minutes, plus a copy in each saved user template (template: "user"). The endpoint returns that latest PDF in seconds, tagged stale (true = an event landed after it — its report may still be in progress) or lands the symbol in missing. Nothing is rendered on fetch: rendering is always empty.
• generate_report_for_stock → /create-full-report writes a new research note (a few minutes), used sparingly. The agent calls it with the ticker alone only when get_latest_report returned the symbol stale with no report on the way, or missing, and the user wants to wait; the note replaces the symbol's report, so later get_latest_report calls return it and report_plan subscribers are notified. 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 (the report get_latest_report returns is current) or has a newer event since — 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 writes the same note steered toward those items (a few minutes) and, like a standard call, replaces the symbol's report. 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 transportcore.py              the FastMCP instance, server instructions and `_send` (backend forwarding)client.py            shared httpx client + inbound-bearer forwardingauth_verifier.py     OAuth resource-server token validation (RS256 via the backend JWKS)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  data_feeds.py          download_dataset (versioned daily feed files), user datasets (draft / save / list / delete)  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/activatepip install -r requirements.txtcp .env.example .env          # set API_BASE_URL, MCP_HOST, MCP_PORTset -a && source .env && set +apython 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 Finance 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 Finance's privacy policy — what's collected, retention windows, and the third parties involved — is published at app.flexreportfinapi.com/privacy (source: PRIVACY.md).