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., "@FilingLens how did data center revenue change for NVDA last year, and what drove it?"
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.
Ask any 10-K. Get the number, the sentence, and the citation.
FilingLens answers questions about US public companies from their SEC filings. Financial figures come straight from the company's XBRL submission (exact, with the tag and accession number); narrative answers cite the filing section with a link to sec.gov. Retrieval is scoped per company — no cross-company mixing.
pip install filinglens # or: uv add filinglensRelated MCP server: edgar-mcp
{
"mcpServers": {
"filinglens": {
"command": "uvx",
"args": ["--from", "filinglens", "filinglens-mcp"],
"env": { "FL_API_KEY": "fl_your_key" }
}
}
}Claude Code: claude mcp add filinglens -e FL_API_KEY=fl_your_key -- uvx --from filinglens filinglens-mcp
Tools: search_company · get_financials · list_metrics · index_company · ingest_status · ask_filing · compare_companies
Without FL_API_KEY the shared demo key is used (20 questions/month). Get a free key at https://filinglens.ai.
from filinglens import FilingLens
fl = FilingLens(api_key="fl_...")
fl.facts("NVDA", metrics=["revenue", "free_cash_flow", "gross_margin"], years=5)
# {'ticker': 'NVDA', 'facts': [{'metric': 'revenue', 'fiscal_year': 2026, 'display': '$215.94B',
# 'tag': 'us-gaap:Revenues', 'accn': '0001045810-26-000021', ...}, ...]}
r = fl.ask("How did data center revenue change and what drove it?", tickers=["NVDA"])
print(r["answer"])
for c in r["citations"]:
print(c["ticker"], c["form"], c["fiscal_year"], c["section"], c["url"])
fl.compare(
["AAPL", "MSFT", "NVDA"],
metrics=["revenue", "net_margin", "free_cash_flow"],
question="Compare margin trends in the latest fiscal year.",
)Async: from filinglens import AsyncFilingLens.
Free (20 questions/mo) · Pro from $15–49/mo by region · API $0.08–0.25 per question · Enterprise with private deployment. Details: https://filinglens.ai/#pricing
FilingLens summarises and cites public SEC filings. It is not investment, legal, tax or accounting advice. Figures are reproduced from company XBRL filings and may be restated; verify with the original filing before relying on them.
MIT licensed. The hosted service is proprietary.
Answer a question from one or more companies' SEC filings with citations (section, form, fiscal year, sec.gov URL). Figures come from XBRL. Requires the ticker to be indexed.
| Name | Required | Description | Default |
|---|---|---|---|
| tickers | Yes | ||
| question | Yes | ||
| fiscal_years | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden: it discloses that figures are sourced from XBRL and that answers come back with citations, which is genuinely useful behavioral context. It stops short of saying what happens when a ticker is not indexed (error? empty result?), how many filings/years can be covered, or anything about latency or limits.
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?
Three compact sentences, front-loaded with the capability and then the precondition. Nothing is redundant, though the second sentence ('Figures come from XBRL') borders on trivia an agent rarely needs.
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?
No output schema, so describing the citation format is appropriate and partially substitutes for one; the indexing precondition covers the main operational gotcha. Gaps remain around the optional fiscal_years parameter and failure behavior for unindexed tickers, but the core picture is present.
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% and there are three parameters, so the description must compensate. It clarifies the intent of 'tickers' ('one or more companies') and hints at fiscal scope via the citation fields, but never explains fiscal_years semantics — notably that its default is null, presumably meaning all years.
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 names a specific verb and resource ('Answer a question from one or more companies' SEC filings') and even characterizes the output shape (citations with section, form, fiscal year, sec.gov URL). It does not contrast itself with plausible siblings such as get_financials or compare_companies, so an agent must infer the boundary on its own.
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 gives one real prerequisite — 'Requires the ticker to be indexed' — which usefully points at index_company/ingest_status, but it never states when to choose ask_filing over get_financials or compare_companies, nor any exclusions. Usage is therefore implied rather than specified.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Side-by-side XBRL comparison of 2–10 companies, optionally with a cited narrative answer.
| Name | Required | Description | Default |
|---|---|---|---|
| metrics | No | ||
| tickers | Yes | ||
| question | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With zero annotations, the description carries the full burden. It does disclose two real behavioral traits: an enforced 2–10 company bound and that narrative output is cited, which tells the agent output is sourced. It says nothing about failure modes, permissions, rate limits, or what the comparison result actually contains.
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?
A single dense sentence with the core capability front-loaded and no filler. Every clause (side-by-side, XBRL, 2–10 bound, optional narrative) adds information.
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?
No output schema, no annotations, and three parameters at 0% schema coverage. The description leaves the metrics parameter undefined and gives no sense of the comparison result shape or when a narrative answer is produced, which is too thin for a multi-entity analysis tool.
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% for all three parameters. The description covers tickers indirectly (the 2–10 companies bound) and question indirectly (the 'cited narrative answer'), but the metrics parameter is never mentioned, so one of three parameters is completely undocumented in both schema and description.
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 (compare) and resource (companies) and adds useful scope details: side-by-side XBRL comparison of 2–10 companies. It implicitly distinguishes itself from single-company siblings like get_financials or ask_filing, but never names them, so sibling differentiation is left to inference.
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?
There is no explicit when-to-use guidance and no when-not-to-use guidance. The phrase 'optionally with a cited narrative answer' hints that a question turns on the narrative mode, but the agent is not told when to prefer compare_companies over get_financials or ask_filing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Exact fiscal-year financials from the company's XBRL filings (revenue, net_income, operating_income, gross_profit, total_assets, total_liabilities, stockholders_equity, cash, operating_cash_flow, capex, free_cash_flow, rnd, sga, eps_diluted, long_term_debt, buybacks, dividends_paid, gross_margin, operating_margin, net_margin, ...). Each value carries its XBRL tag and filing accession number.
| Name | Required | Description | Default |
|---|---|---|---|
| years | No | ||
| ticker | Yes | ||
| metrics | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It usefully discloses that each value is tagged with its XBRL tag and filing accession number, which is real provenance information beyond the schema. However, it omits critical traits: read-only safety, whether data must be pre-ingested (index_company/ingest_status siblings hint at a prerequisite), error behavior for unindexed tickers, and how missing metrics are handled.
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?
Purpose and data source are front-loaded in the first clause, and the metric enumeration, while long, is genuinely informative rather than filler. The trailing sentence about XBRL tags earns its place. Slightly heavy on the parenthetical list.
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?
No output schema and no annotations, so the description should do more. It partially describes return content (values plus XBRL tag and accession number) but omits invocation prerequisites and parameter semantics, leaving the agent to guess at indexing requirements and argument formats.
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 compensate. It effectively documents the metrics parameter by listing valid metric names (revenue, net_income, free_cash_flow, etc.) and hints at the years parameter via 'fiscal-year', but leaves ticker unexplained and gives no format for years or how the metrics list interacts with the defaults.
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?
States a specific verb (get) and resource (fiscal-year financials), names the data source (the company's XBRL filings), and enumerates the exact metrics returned. An agent can readily distinguish this from siblings like compare_companies or ask_filing.
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?
No when-to-use guidance is given. The description never says when this tool should be chosen over ask_filing, search_company, or compare_companies, nor any prerequisites (e.g. whether the company must be indexed first via index_company). Usage is only implied by the subject matter.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Index the latest filings (default: most recent 10-K) for a ticker so ask_filing can use it. Returns a job id; indexing takes ~20–60 seconds. Poll with ingest_status.
| Name | Required | Description | Default |
|---|---|---|---|
| forms | No | ||
| limit | No | ||
| ticker | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses async job semantics, that a job id is returned, the 20–60 second latency, and the polling tool. It omits auth/permission needs and what happens on re-indexing or failure.
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?
Two short sentences, both front-loaded with the action, scope, and latency before the polling hint. No wasted wording.
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 3-param mutation-style tool with no annotations and no output schema, the description supplies the essential return value (job id), the timing expectation, and the follow-up step. Gaps remain around `limit`/`forms` semantics and re-index behavior.
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 compensate. It implicitly covers ticker and the default form (10-K), partially illuminating the `forms` parameter, but says nothing about `limit` or the array syntax/format for forms, leaving meaningful gaps.
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?
States a specific verb (index) and resource (latest filings for a ticker), names the default scope (most recent 10-K), and identifies the downstream consumer (ask_filing), which sharply separates it from siblings like search_company and 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 tells the agent when this is needed (before ask_filing can use filings) and routes polling to the sibling ingest_status. There is no explicit 'when not to use' or guidance for already-indexed tickers, but the context is otherwise clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check an index_company job.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only says 'Check' and gives no information about authentication, read-only nature, rate limits, polling behavior, or what happens if the job is missing. This is essentially no behavioral context.
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 a single front-loaded sentence with no wasted words. However, it is so sparse that it borders on under-specification rather than serving as a complete tool definition, which limits its usefulness despite being concise.
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 one-parameter tool with no output schema and no annotations, the description should at least explain what 'check' returns or how the job_id is obtained. It provides only a minimal purpose statement and leaves critical operational context 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?
Schema description coverage is 0% for the single required job_id parameter. The description adds only marginal meaning by tying the job to index_company, but does not describe the parameter name, format, origin constraints, or what a valid job_id looks like.
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?
States a verb ('Check') and a resource ('index_company job'), but 'check' is vague about what is returned or verified, and 'index_company job' is ambiguous without further context. It hints at differentiation from the sibling index_company, but does not explicitly distinguish the two.
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?
No explicit when-to-use or when-not-to-use guidance is given. The phrase 'index_company job' weakly implies this is used after starting a job with index_company, but there is no clear routing or alternative selection information.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List every metric key get_financials understands.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden, and it discloses almost nothing: no statement that this is a side-effect-free read, that it takes no inputs, or what the returned collection looks like. Only the scope (keys get_financials accepts) hints at behavior.
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?
A single front-loaded sentence with no filler; a discovery tool needs no more preamble than this.
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?
With no output schema and no annotations, the description should have covered the return shape (e.g. a flat list of key names) and confirmed the read-only, argument-free nature. It is adequate for such a simple tool but leaves the response form unspecified.
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 tool takes zero parameters and the schema is an empty object, so there is nothing for the description to disambiguate. Baseline of 4 applies for a no-argument tool.
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?
Clear verb (List) plus resource (metric key) and an explicit tie to the consuming sibling get_financials, which is exactly what distinguishes a discovery tool from the consumer tool. An agent can tell instantly that this enumerates valid metric keys rather than returning financial values.
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?
By naming get_financials the description implies this is the prerequisite discovery step before calling that tool, but it never states the when-to-use condition or that no arguments are needed. Usage is inferable rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find a US-listed company's ticker and CIK by name or ticker fragment.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does disclose the return fields (ticker and CIK) and a real scope constraint (US-listed only). It says nothing about match behavior (fuzzy vs exact), result count limits, or what happens when nothing matches, which matters for a search tool.
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?
One sentence, front-loaded with the verb and resource, with the input modes trailing. Nothing wasted and nothing padded.
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 one-parameter lookup with no output schema and no annotations, the description covers purpose and inputs but leaves result-set behavior (single vs multiple matches, ranking, empty results) unspecified. Adequate, but an agent must guess how to interpret the response.
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 coverage is 0% and the single parameter is documented only as 'Query', so the description is the only source of meaning. It compensates well by stating the accepted values are a company name or a ticker fragment, which is exactly what an agent needs to form a valid call.
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?
Specific verb ('Find') plus a precise resource ('a US-listed company's ticker and CIK') and the accepted input forms. An agent can tell this apart from ask_filing or get_financials, though it never distinguishes itself from the similarly named index_company sibling.
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?
Usage is implied by 'by name or ticker fragment', which tells the agent what to supply, but there is no explicit when-to-use statement, no prerequisites (e.g. must the company be indexed first?), and no mention of alternatives like index_company.
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.0ask_filingcompare_companiesget_financialsindex_companyingest_statuslist_metricssearch_companyScored across 7 tools
Each tool targets a distinct step of the filing-analysis workflow (discover company, index, poll, query, exact numbers, compare). The only real overlap is ask_filing vs get_financials, since a numeric question could plausibly route to either, and get_financials vs compare_companies differ mainly by company count.
Names are uniformly snake_case and mostly follow a verb_noun pattern (list_metrics, index_company, ask_filing, search_company, get_financials, compare_companies). ingest_status is the one mild deviation, being a noun-style status check rather than an explicit verb_object.
Seven tools is well-scoped for an SEC-filing analysis server, with each tool owning a clear stage of the workflow (search, index, poll, QA, financials, comparison). No tool feels redundant or superfluous.
The surface covers the full pipeline: company lookup, indexing, job polling, cited QA, exact financials, metric discovery, and multi-company comparison. Minor gaps remain, such as no way to list already-indexed companies, inspect stored filings, or delete/re-index stale data.
Access SEC filings efficiently (10-K, 10-Q, etc), save time and tokens, and get cited answers.
SEC filing intelligence for AI agents. Financials, screening, peer comparison for 5,000+ companies.
Primary-source SEC filing intelligence and financial/disclosure reconciliation for AI agents.
Search SEC filings, read 10-K/8-K, query XBRL facts, track Form 4 insider trades.
