Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@datavidence-financials Get AAPL's FY2023 financials with ratios."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Normalized US-GAAP financial statements from SEC EDGAR — income statement, balance sheet, and cash flow — exposed as Model Context Protocol (MCP) tools for LLM agents (Claude Desktop, LangChain, and custom frameworks). Every value is traceable to its source SEC filing, and figures can be pulled as originally reported for any date (no look-ahead), for backtests.
This is the open-source, AI-native layer for the Datavidence Financials API — a standalone stdio server that forwards over HTTPS to the REST API (bring your own key). The connector is MIT-licensed; the underlying API is a commercial service.
Run it with uv — it installs into a throwaway environment:
FL_API_KEY=sandbox_demo_key uvx datavidence-financialssandbox_demo_key returns sample data with no signup — good for a first run.
Swap in your real key for live SEC data. Or install it as a persistent tool with
pipx install datavidence-financials.
Related MCP server: Aegis Gov SEC Filings MCP
Add to claude_desktop_config.json, then fully quit (Cmd+Q) and reopen Claude
Desktop — the tools appear:
{
"mcpServers": {
"datavidence-financials": {
"command": "uvx",
"args": ["datavidence-financials"],
"env": { "FL_API_KEY": "sandbox_demo_key" }
}
}
}Then ask, e.g., "get AAPL's FY2023 financials with ratios."
get_financials — normalized income statement + balance sheet + cash flow
for one company and fiscal year, from SEC EDGAR XBRL. Supports as_of
(point-in-time, as originally reported), include_provenance (per-value SEC
accession, filed date, and direct EDGAR source URL), and include_ratios
(margins, ROA/ROE, leverage).
get_financials_batch — the same, for up to 25 companies in one call
(comma-separated tickers/CIKs). Per-symbol results; counts as a single quota
unit, so one bad symbol never fails the batch.
list_filings — a company's recent SEC filings (newest first) from the
EDGAR submissions index; filter by form (e.g. 10-K). Use it to discover which
fiscal years are available before calling get_financials.
get_usage — the key's monthly quota (tier, used, remaining, reset). Free
to call; consumes no quota.
Errors surface the API's recovery_action hint, so agents self-correct.
Variable | Default | Notes |
| (none) | Your API key. |
|
| Point at a marketplace gateway for metered BYOK access. |
|
| Header to send the key in (e.g. |
|
| Per-request timeout, in seconds. |
pip install -e .
FL_API_KEY=sandbox_demo_key python -m mcp_server.server # stdio transportAPI & docs: https://financials.datavidence.ai
Get a key (RapidAPI): https://rapidapi.com/datavidence-ykNLbvGmT/api/datavidence-financials-api
Security: see SECURITY.md to report a vulnerability privately.
MIT © 2026 Datavidence LLC. The connector is open-source; the underlying Datavidence Financials API is a commercial service.
Retrieve normalized US-GAAP financial statements (income statement, balance sheet, cash flow) for one company and fiscal year, from SEC EDGAR XBRL.
Identify the company by ticker OR cik. Use as_of (ISO YYYY-MM-DD) to get
the figures as originally reported on that date — no look-ahead bias — for
backtests. Set include_provenance=true to attach, for every value, the SEC
accession, filed date, and a direct EDGAR source URL for citation. Set
include_ratios=true for margins, ROA/ROE, and leverage derived from the same
statements. Returns the normalized data object.
| Name | Required | Description | Default |
|---|---|---|---|
| cik | No | ||
| year | Yes | ||
| as_of | No | ||
| ticker | No | ||
| include_ratios | No | ||
| include_provenance | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must disclose behavioral traits on its own. It does state that `as_of` yields 'figures as originally reported on that date — no look-ahead bias — for backtests', which is a key behavioral guarantee. It also notes that include_ratios derives margins, ROA/ROE, and leverage 'from the same statements.' However, it does not disclose what happens when both ticker and cik are provided, what happens if no match is found, or any rate/error behavior. The core behavioral contract (returns normalized data) is present but not exhaustive, so a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with line breaks, front-loading the core purpose in the first sentence, then elaborating on identification, as_of, and flags. It is concise for the amount of information delivered — no redundant phrases or fluff. Every sentence adds value, making it efficient for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description should clarify what is returned; it says 'Returns the normalized data object' but does not detail the structure. It also omits edge cases like conflicting identifiers, missing data for a year, or error handling. However, for a financial data retrieval tool, it covers the essential usage aspects: identification, look-back bias prevention, and optional enrichments. The gaps are minor relative to the tool's complexity, so a 4 is justified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the full burden of parameter explanation. It explains ticker and cik as alternative identifiers, year is implied by 'fiscal year', as_of is described with its backtest purpose, include_provenance is explained as attaching SEC accession, filed date, and EDGAR URL, and include_ratios is described as adding margins, ROA/ROE, and leverage. Every parameter is given meaning beyond the bare schema, fully compensating for the zero coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb ('Retrieve') and a precise resource: 'normalized US-GAAP financial statements (income statement, balance sheet, cash flow) for one company and fiscal year, from SEC EDGAR XBRL.' It explicitly scopes to a single company and fiscal year, which distinguishes it from the sibling get_financials_batch. The identification via ticker OR cik is also stated, leaving no ambiguity about the tool's core function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear guidance on identification ('Identify the company by `ticker` OR `cik`'), explains the purpose of `as_of` for backtests with no look-ahead bias, and explains what the include flags do. It does not explicitly name alternatives or state when not to use this tool, but the single-company/fiscal-year scope implicitly contrasts with get_financials_batch. This is strong contextual guidance but lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve normalized US-GAAP financials for MANY companies in one call — use this to compare peers or scan a set for a single fiscal year.
Pass companies as comma-separated tickers (e.g. "AAPL,MSFT,GOOGL") and/or
ciks; up to 25 symbols total, all for the same year. as_of,
include_provenance, and include_ratios behave as in get_financials and
apply to every symbol. Each company returns its own result — either data or
an error with a recovery hint — so one bad symbol never fails the batch. The
whole call counts as a SINGLE request against your monthly quota, so prefer it
over many get_financials calls when you need several companies.
| Name | Required | Description | Default |
|---|---|---|---|
| ciks | No | ||
| year | Yes | ||
| as_of | No | ||
| tickers | No | ||
| include_ratios | No | ||
| include_provenance | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and does so thoroughly: per-company results with data/error and recovery hints, one bad symbol not failing the batch, single-request quota accounting, and the same-year constraint. This goes far beyond what the schema alone reveals.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The definition is front-loaded with purpose, then lists constraints and behavior in a compact paragraph with no filler. Every sentence adds either selection guidance, parameter semantics, failure behavior, or quota implications.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no annotations and no output schema, the description covers purpose, limits, error handling, per-company return semantics, and quota impact. An agent has what it needs to decide when to call it and what to expect from individual results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain the parameters itself. It defines ticker/cik input as comma-separated symbols, a 25-symbol maximum, the single-year requirement, and delegates shared meanings (as_of, include_provenance, include_ratios) to the get_financials semantics. This is substantial added meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description states a specific verb and resource ('Retrieve normalized US-GAAP financials') plus the batching scope ('for MANY companies in one call'), and explicitly frames it as the right tool for comparing peers or scanning a set. This clearly differentiates it from sibling get_financials.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It says when to use the tool ('compare peers or scan a set for a single fiscal year') and names the alternative with the selection condition ('prefer it over many get_financials calls when you need several companies'). The single-year and 25-symbol constraints further clarify appropriate use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report the calling API key's current monthly quota: tier, monthly limit, requests used and remaining this billing month, and when it resets.
Free to call — it does NOT consume quota. Check it before a large batch or a long run so you can pace requests and avoid a hard rate-limit (429).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden, and it excels by explicitly stating that the call is free and does not consume quota. It also discloses what data is returned and warns about the hard rate-limit, giving the agent a complete behavioral picture.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the tool's purpose and output contents, followed immediately by practical guidance. Every sentence serves a distinct function: what it reports, that it is free, and when to use it.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read-only reporting tool with no output schema, the description is fully complete: it names the returned fields, confirms no quota impact, and provides clear usage timing. Nothing needed for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so schema description coverage is vacuously 100% and there is nothing for the description to add about parameters. Per the baseline for 0-parameter tools, this is adequate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Report') and a precise resource (the calling API key's current monthly quota), then enumerates the exact details returned. It is immediately distinguishable from the sibling tools, which concern financials and filings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit context: check this tool before a large batch or long run to pace requests and avoid 429s. It does not name an alternative because none is relevant among the sibling tools, but it clearly explains when to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List a company's recent SEC filings (newest first) from the EDGAR submissions index — a lean company header plus filing rows.
Identify the company by ticker OR cik. Optionally filter by form (e.g.
"10-K", prefix-matched so it includes amendments like "10-K/A") and cap the
number of rows with limit (1-100). Use this to discover which fiscal years
or filings are available before calling get_financials.
| Name | Required | Description | Default |
|---|---|---|---|
| cik | No | ||
| form | No | ||
| limit | No | ||
| ticker | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden, and it delivers: it discloses newest-first ordering, the EDGAR submissions index source, prefix matching for forms (including amendments), the limit range of 1-100, and the output as a lean header plus rows. It could also clarify behavior when both ticker and cik are supplied, but the provided details are substantial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is tightly structured: an opening function statement, a parameter explanation sentence, and a use-case sentence. Every sentence earns its place, with no redundant or filler text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with no annotations and no output schema, the description explains what it returns, how to identify the company, available filters, and why an agent should call it. It is complete enough to invoke correctly and to know what to expect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain all parameters, and it does. Each parameter is covered: ticker and cik for identification, form with an example and prefix-matching behavior, and limit with an explicit 1-100 range. This exceeds the schema's bare property names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'List a company's recent SEC filings (newest first) from the EDGAR submissions index.' It also describes the output shape as 'a lean company header plus filing rows,' making the tool's function unambiguous. It further distinguishes itself from siblings by explicitly positioning this tool as a discovery step before calling get_financials.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: use this to discover which fiscal years or filings are available before calling get_financials. It does not explicitly mention alternatives like get_financials_batch or exclusion cases, but the sequencing guidance is strong enough to inform typical selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.2get_financialsget_financials_batchget_usagelist_filingsScored across 4 tools
get_financials and get_financials_batch are related but clearly separated by single-company vs multi-company use; list_filings and get_usage serve distinct purposes. The only potential confusion is batch vs single financials, but the descriptions make the intended use explicit.
Three tools follow a consistent get_* pattern, while list_filings uses list_ instead of get_. This is a minor deviation, but the naming remains predictable and readable overall.
Four tools is well-scoped for a financial data server: usage monitoring, single-company financials, batch financials, and filing discovery each serve a necessary and distinct role. No tool feels redundant or missing as a core primitive.
The tool set covers the main workflow of discovering filings and retrieving normalized financial statements, plus a batch variant and quota monitoring. Minor gaps exist, such as no explicit company search or multi-year time-series retrieval, but these are workarounds rather than dead ends.
Agent-native SEC filing data: statements assembled, filings read and synthesized. No API key.
SEC EDGAR financials, insider trading, and economic data for AI agents. US GAAP + IFRS.
Primary-source SEC filing intelligence and financial/disclosure reconciliation for AI agents.
SEC filing intelligence for AI agents. Financials, screening, peer comparison for 5,000+ companies.
