US MCP tools - stockinsights.ai APIs

The US server at https://api-us.stockinsights.ai/mcp exposes these eight read-only tools. Ask your assistant a research question to use them, or use this reference when building an MCP client.

Company research

`resolve_companies`

Resolve US company names or ticker symbols to ranked company matches. Each match includes company_id, company_name, a plain ticker, and a match score.

Input	Description
`entities` (required)	1–20 company names or ticker symbols, such as `Apple Inc`, `AAPL`, or `MSFT`. Use plain identifiers without exchange prefixes.
`limit_per_entity`	Matches per input: 1–10, default 5.

Use the returned plain ticker in subsequent tools.

`filter_companies`

Screen listed US companies and retrieve CIK identifiers, industry classifications, and stored market-cap snapshots. Delisted companies are excluded. Supply at least one screening criterion:

Input	Description
`tickers`	Up to 50 plain tickers, such as `AAPL` or `BRK.B`.
`marketcap_categories`	Any of `mega`, `large`, `mid`, `small`, `micro`, or `nano`.
`industry_filters`	Up to 20 exact classification objects using `industry_sector` and `industry`. Fields within an object combine with AND; objects combine with OR.
`marketcap`	Numeric filter in USD, unscaled. Accepts `eq` alone, or lower and upper bounds using `gt`, `gte`, `lt`, and `lte`.
`sort`	`field`: `company_name`, `ticker`, or `marketcap`. `direction`: `asc` or `desc`. Defaults to market cap descending.
`limit`, `cursor`	1–100 companies, default 20. Continue with `meta.next_cursor` using identical filters and sort.

For example, marketcap: { "gte": 1000000000 } selects companies with market cap of at least USD 1 billion. US screening supports market cap; share-price, 52-week high/low, and PE-ratio filters are unavailable.

Filing research

`list_filings`

List filing metadata newest first, across the market or for selected companies. Results include filing IDs and citation links.

Input	Description
`filing_type` (required)	One of `earnings-transcript`, `10-K`, `10-Q`, or `20-F`.
`filters.tickers`	Up to 100 plain tickers. Omit for a market-wide feed.
`filters.fiscal_years`	Years such as `FY25`, for 10-K and 20-F filings only. Matches the stored filing report-end year.
`filters.fiscal_quarters`	Quarters such as `FY25Q1`, for 10-Q filings and earnings transcripts only.
`limit`	1–50 filings, default 50.

Use get_announcements for corporate disclosures, search_filings to find passages, and get_filing_content to read a selected filing.

`search_filings`

Search earnings transcripts, 10-K, 10-Q, and 20-F filings. Returns matching passages with filing IDs, chunk numbers when available, citation links, and retrieval status.

Input	Description
`search_method` (required)	`keyword` for exact terms, quoted phrases, or named metrics; `semantic` for concepts, guidance, or management commentary.
`query` (required)	Search text, 1–500 characters.
`filters.tickers`	Up to 100 plain tickers. Required when supplying a filters object; use `null` or an empty array for all companies.
`filters.filing_criteria`	Up to four objects. Required when supplying a filters object; use an empty array for all supported types. Each object requires `filing_type` and `period`.
`filters.latest`	Defaults to `true` for criteria without an explicit period. Set `false` to search all history for those criteria.

Each criterion’s period is either null to follow filters.latest, or an object with calendar_years (such as "2025") or fiscal_quarters (such as "FY25Q1"). Explicit periods take precedence over latest. Omitting filters searches the latest filing of every supported type across all companies. For example, search the latest NVIDIA earnings transcript with these request fields:

{
  "search_method": "semantic",
  "query": "management outlook on data center demand",
  "filters": {
    "tickers": ["NVDA"],
    "filing_criteria": [
      { "filing_type": "earnings-transcript", "period": null }
    ],
    "latest": true
  }
}

`get_filing_content`

Read one US filing by chunk. Select the filing using either its document_id, or a ticker together with time_scope.

Input	Description
`filing_type` (required)	`earnings-transcript`, `10-K`, `10-Q`, or `20-F`.
`document_id`	The `filing_id` returned by `list_filings` or `search_filings`. Selects that exact filing; omit `ticker` and `time_scope`.
`ticker`	One plain ticker. Required with `time_scope` when `document_id` is absent.
`time_scope`	`{ "mode": "latest" }`, or `mode: "period"` with `fiscal_year` for 10-K/20-F or `fiscal_quarter` for transcripts/10-Q.
`chunk_selection`	Up to 10 chunks using `mode: "range"` with `start_chunk` and `end_chunk`, or `mode: "chunks"` with a `chunks` array. Chunk numbers start at 1.

Use the chunk numbers returned by search results or their #chunk<n> citation anchors. Without chunk_selection, the response starts at chunk 1 and stops at a size limit. Check truncated and total_chunks to determine whether you need more content. US filings use chunks rather than page selections.

Corporate announcements

`get_announcements`

Fetch AI summaries of US corporate announcements, newest first, with company information and citation links.

Input	Description
`tickers` (required)	1–50 plain US tickers. Screen companies first and query in batches for a broader universe.
`category`	Exact category names, such as `Earnings Reports`. Set to `null` for all categories.
`time_period`	`start_date` and `end_date` in `YYYY-MM-DD` format. Omit or set to `null` for the last month.
`sentiment`	Any of `positive`, `negative`, or `neutral`.
`significance`	`true` for significant announcements only; `false` for non-significant only.
`page`, `limit`	Page starts at 1. Page size is 1–50, default 50.

Results report the searched date window, meta.total_count, and has_more. Unmatched tickers are reported in unresolved_tickers; they do not widen the search to all companies.

Financial statements

`describe_structured_financial_tables`

Inspect column names, types, and descriptions before writing a financial query. Pass a required table_names array containing one or more of:

Table	Data
`us_companies`	Company details and identifiers.
`us_10q_filing`	Quarterly filing records.
`us_20f_filing`	Annual filing records for 10-K and 20-F forms.
`us_xbrl_income_statements`	Income statement facts.
`us_xbrl_balance_sheets`	Balance sheet facts.
`us_xbrl_cash_flow_statements`	Cash flow statement facts.

`run_structured_financial_query`

Run one read-only PostgreSQL query over the supported US tables to retrieve reported financials, compare companies, or calculate trends and ratios.

Input	Description
`query` (required)	One read-only PostgreSQL query. Bind placeholders are unsupported.
`max_rows`	1–1,000 rows, default 100.

Returns rows and a truncated flag. Inspect columns with describe_structured_financial_tables first. Join XBRL facts through filing_id to us_10q_filing.id for quarterly facts or us_20f_filing.id for annual facts, then join filings to us_companies through company_id. Filter annual filings by form_type to distinguish 10-K and 20-F. Facts use concept_local_name, report_start_date, and report_end_date. Use filter_companies for ordinary company screening.

Example questions

“Find US semiconductor companies with market cap above USD 10 billion.”
“What did NVIDIA management say about data center demand in its latest call?”
“Read the risk discussion in Apple’s latest 10-K and cite the relevant passages.”
“Compare Microsoft’s revenue and cash flow over the last three reported fiscal years.”

​Company research

​resolve_companies

​filter_companies

​Filing research

​list_filings

​search_filings

​get_filing_content

​Corporate announcements

​get_announcements

​Financial statements

​describe_structured_financial_tables

​run_structured_financial_query

​Example questions