Canary Data

MCP Server — Developer Documentation

Reference for the Canary Data Model Context Protocol (MCP) server, including available tools, supported markets, data freshness, and rate limits.

Tool Reference

new_accounting_issue

Retrieves accounting & disclosure flags for a company identified by ticker and country — the full set shown on the web Accounting tab, spanning the entire accounting_and_disclosure category (revenue/cost recognition, receivables, inventory, auditor and disclosure changes, new accounting issues, and more). Returns paginated flag records, each containing the flag date, severity, title, description, sources, and a metadata map (filing URLs and forms for filing-comparison flags).

Input Parameters

Parameter Type Required Description
ticker string required Company ticker symbol (e.g. AAPL)
country string required ISO 3166-1 alpha-2 country code (e.g. US)
date_from string optional Start of date range — ISO 8601 format (YYYY-MM-DD)
date_to string optional End of date range — ISO 8601 format (YYYY-MM-DD)
page integer optional Page number. Defaults to 1
per_page integer optional Results per page. Defaults to 50

Response Shape — flags found

{ "data": [ { "date": "2024-03-15", "severity": "high", "title": "...", "description": "...", "flag_type": "change_in_revenue_cost_recognition", "company": { "id": 1234, "name": "Acme Corp", "ticker": "ACME", "exchange": "NASDAQ", "isins": ["US0123456789"], "ciks": ["0001234567"] }, "sources": ["..."], "metadata": { "filing_url": "https://...", "filing_url_prev": "https://...", "form": "10-K", "form_prev": "10-K", "current_date": "2024-03-15", "prev_date": "2023-03-10", "text": ["..."] } } ], "meta": { "total": 42, "page": 1, "per_page": 50 } }

Response Shape — no flags found

When data is empty, meta.coverage is included as a hint. It carries the echoed ticker and country so the caller can confirm the parameters that were searched, along with a human-readable hint string. When a date_from or date_to filter was supplied, the active date bounds are also echoed and the hint clarifies that the empty result is specific to the requested range — flags may exist outside it.

{ "data": [], "meta": { "total": 0, "page": 1, "per_page": 50, "coverage": { "ticker": "AAPL", "country": "US", "hint": "No flags of this type were found for AAPL (US)." } } }

Response Shape — no flags found (with date range)

{ "data": [], "meta": { "total": 0, "page": 1, "per_page": 50, "coverage": { "ticker": "AAPL", "country": "US", "date_from": "2024-01-01", "date_to": "2024-06-30", "hint": "No flags of this type were found for AAPL (US) in the requested date range." } } }
insider_trading

Retrieves insider trading flags (all sub-types) for a company identified by ticker and country. Returns paginated flag records derived from regulatory filings, each containing the flag date, severity, description, and structured transaction details.

Input Parameters

Parameter Type Required Description
ticker string required Company ticker symbol (e.g. AAPL)
country string required ISO 3166-1 alpha-2 country code (e.g. US)
date_from string optional Start of date range — ISO 8601 format (YYYY-MM-DD)
date_to string optional End of date range — ISO 8601 format (YYYY-MM-DD)
page integer optional Page number. Defaults to 1
per_page integer optional Results per page. Defaults to 50

Response Shape — flags found

{ "data": [ { "date": "2024-03-15", "severity": "medium", "description": "...", "flag_type": "insider_trading", "company": { "id": 1234, "name": "Acme Corp", "ticker": "ACME", "exchange": "NASDAQ", "isins": ["US0123456789"], "ciks": ["0001234567"] }, "transactions_info": { ... }, "sources": ["..."] } ], "meta": { "total": 18, "page": 1, "per_page": 50 } }

Response Shape — no flags found

When data is empty, meta.coverage is included as a hint. It carries the echoed ticker and country so the caller can confirm the parameters that were searched, along with a human-readable hint string. When a date_from or date_to filter was supplied, the active date bounds are also echoed and the hint clarifies that the empty result is specific to the requested range — flags may exist outside it.

{ "data": [], "meta": { "total": 0, "page": 1, "per_page": 50, "coverage": { "ticker": "AAPL", "country": "US", "hint": "No flags of this type were found for AAPL (US)." } } }

Response Shape — no flags found (with date range)

{ "data": [], "meta": { "total": 0, "page": 1, "per_page": 50, "coverage": { "ticker": "AAPL", "country": "US", "date_from": "2024-01-01", "date_to": "2024-06-30", "hint": "No flags of this type were found for AAPL (US) in the requested date range. Flags may exist outside the specified range." } } }
fundamentals_analysis

Retrieves fundamental business risk flags for a company identified by ticker and country — the full set shown on the web Fundamentals tab, spanning the entire fundamental_business category (declining sales and margins, going-concern letters, financial distress and high leverage, customer/supplier concentration, competitive and country risk, and AI/competitive positioning shifts). Returns paginated flag records, each containing the flag date, severity, title, description, sources, and a metadata map whose shape varies by flag type.

Input Parameters

Parameter Type Required Description
ticker string required Company ticker symbol (e.g. AAPL)
country string required ISO 3166-1 alpha-2 country code (e.g. US)
date_from string optional Start of date range — ISO 8601 format (YYYY-MM-DD)
date_to string optional End of date range — ISO 8601 format (YYYY-MM-DD)
page integer optional Page number. Defaults to 1
per_page integer optional Results per page. Defaults to 50

Response Shape — flags found

{ "data": [ { "date": "2024-03-15", "severity": "high", "title": "...", "description": "...", "flag_type": "going_concern_letter", "company": { "id": 1234, "name": "Acme Corp", "ticker": "ACME", "exchange": "NASDAQ", "isins": ["US0123456789"], "ciks": ["0001234567"] }, "sources": ["..."], "metadata": { } } ], "meta": { "total": 7, "page": 1, "per_page": 50 } }

Response Shape — no flags found

When data is empty, meta.coverage is included as a hint. It carries the echoed ticker and country so the caller can confirm the parameters that were searched, along with a human-readable hint string. When a date_from or date_to filter was supplied, the active date bounds are also echoed and the hint clarifies that the empty result is specific to the requested range — flags may exist outside it.

{ "data": [], "meta": { "total": 0, "page": 1, "per_page": 50, "coverage": { "ticker": "AAPL", "country": "US", "hint": "No flags of this type were found for AAPL (US)." } } }

Response Shape — no flags found (with date range)

{ "data": [], "meta": { "total": 0, "page": 1, "per_page": 50, "coverage": { "ticker": "AAPL", "country": "US", "date_from": "2024-01-01", "date_to": "2024-06-30", "hint": "No flags of this type were found for AAPL (US) in the requested date range." } } }
fraud_and_malfeasance

Retrieves fraud & malfeasance flags for a company identified by ticker and country — combining two categories: illegal_or_questionable (fraud, illegal activity, stock manipulation, investigations, regulatory scrutiny, civil lawsuits) and questionable_associations (problematic shareholders, underwriters, business partners, SPAC/reverse-merger history, stock promoters, and listing-jurisdiction risk). Returns paginated flag records, each containing the flag date, severity, title, description, sources, and a metadata map whose shape varies by flag type.

Input Parameters

Parameter Type Required Description
ticker string required Company ticker symbol (e.g. AAPL)
country string required ISO 3166-1 alpha-2 country code (e.g. US)
date_from string optional Start of date range — ISO 8601 format (YYYY-MM-DD)
date_to string optional End of date range — ISO 8601 format (YYYY-MM-DD)
page integer optional Page number. Defaults to 1
per_page integer optional Results per page. Defaults to 50

Response Shape — flags found

{ "data": [ { "date": "2024-03-15", "severity": "high", "title": "...", "description": "...", "flag_type": "business_fraud", "company": { "id": 1234, "name": "Acme Corp", "ticker": "ACME", "exchange": "NASDAQ", "isins": ["US0123456789"], "ciks": ["0001234567"] }, "sources": ["..."], "metadata": { } } ], "meta": { "total": 5, "page": 1, "per_page": 50 } }

Response Shape — no flags found

When data is empty, meta.coverage is included as a hint. It carries the echoed ticker and country so the caller can confirm the parameters that were searched, along with a human-readable hint string. When a date_from or date_to filter was supplied, the active date bounds are also echoed and the hint clarifies that the empty result is specific to the requested range — flags may exist outside it.

{ "data": [], "meta": { "total": 0, "page": 1, "per_page": 50, "coverage": { "ticker": "AAPL", "country": "US", "hint": "No flags of this type were found for AAPL (US)." } } }

Response Shape — no flags found (with date range)

{ "data": [], "meta": { "total": 0, "page": 1, "per_page": 50, "coverage": { "ticker": "AAPL", "country": "US", "date_from": "2024-01-01", "date_to": "2024-06-30", "hint": "No flags of this type were found for AAPL (US) in the requested date range." } } }
management_background

Retrieves management track-record & background flags for a company identified by ticker and country — the full management_track_record category: executive and board turnover, prior bankruptcies/delistings, related-party transactions and insider enrichment, nepotism, poor capital allocation, insider buying/selling behaviour, and related governance signals. Returns paginated flag records, each containing the flag date, severity, title, description, sources, and a metadata map whose shape varies by flag type.

Input Parameters

Parameter Type Required Description
ticker string required Company ticker symbol (e.g. AAPL)
country string required ISO 3166-1 alpha-2 country code (e.g. US)
date_from string optional Start of date range — ISO 8601 format (YYYY-MM-DD)
date_to string optional End of date range — ISO 8601 format (YYYY-MM-DD)
page integer optional Page number. Defaults to 1
per_page integer optional Results per page. Defaults to 50

Response Shape — flags found

{ "data": [ { "date": "2024-03-15", "severity": "high", "title": "...", "description": "...", "flag_type": "ceo_turnover", "company": { "id": 1234, "name": "Acme Corp", "ticker": "ACME", "exchange": "NASDAQ", "isins": ["US0123456789"], "ciks": ["0001234567"] }, "sources": ["..."], "metadata": { } } ], "meta": { "total": 9, "page": 1, "per_page": 50 } }

Response Shape — no flags found

When data is empty, meta.coverage is included as a hint. It carries the echoed ticker and country so the caller can confirm the parameters that were searched, along with a human-readable hint string. When a date_from or date_to filter was supplied, the active date bounds are also echoed and the hint clarifies that the empty result is specific to the requested range — flags may exist outside it.

{ "data": [], "meta": { "total": 0, "page": 1, "per_page": 50, "coverage": { "ticker": "AAPL", "country": "US", "hint": "No flags of this type were found for AAPL (US)." } } }

Response Shape — no flags found (with date range)

{ "data": [], "meta": { "total": 0, "page": 1, "per_page": 50, "coverage": { "ticker": "AAPL", "country": "US", "date_from": "2024-01-01", "date_to": "2024-06-30", "hint": "No flags of this type were found for AAPL (US) in the requested date range." } } }
kpi_snapshot

Retrieves the most recent KPI per metric for a company identified by ticker and country. Returns one entry per distinct metric (e.g. Revenue, EPS, Active Users), each showing the value reported in the most recent earnings call transcript. Supports filtering by metric type and date range. Use the after / before cursors for pagination. Use id values from the response entries to fetch full historical time series with the kpi_history tool.

Input Parameters

Parameter Type Required Description
ticker string required Company ticker symbol (e.g. AAPL)
country string required ISO 3166-1 alpha-2 country code (e.g. US)
type string optional Filter by metric type: financial or non_financial
date_from string optional Only include metrics whose most recent filing is on or after this date — ISO 8601 (YYYY-MM-DD)
date_to string optional Only include metrics whose most recent filing is on or before this date — ISO 8601 (YYYY-MM-DD)
limit integer optional Results per page. Defaults to 25, max 100
after string optional Opaque cursor for forward pagination (from meta.after of the previous response)
before string optional Opaque cursor for backward pagination (from meta.before of the previous response)

Response Shape

{ "data": [ { "id": "281522b1-f3a8-48ce-9d7b-10d1e52a9f7f", "metric": "Revenue", "type": "financial", "filing_date": "2026-01-29", "value": "$143.8 billion", "period": "Q1 2026", "commentary": "Up 16% year-over-year, a best-ever quarter." } ], "meta": { "after": "<opaque_cursor>", "before": null } }
kpi_history

Retrieves the full historical time series for a specific KPI metric identified by the id of any entry returned by kpi_snapshot. Returns all historical values for that metric and company, ordered from most recent to oldest. Supports date range filtering and cursor-based pagination.

Input Parameters

Parameter Type Required Description
id string required UUID of any KPI entry returned by kpi_snapshot
date_from string optional Start of date range — ISO 8601 format (YYYY-MM-DD)
date_to string optional End of date range — ISO 8601 format (YYYY-MM-DD)
limit integer optional Results per page. Defaults to 25, max 100
after string optional Opaque cursor for forward pagination
before string optional Opaque cursor for backward pagination

Response Shape

{ "data": [ { "id": "281522b1-f3a8-48ce-9d7b-10d1e52a9f7f", "metric": "Revenue", "type": "financial", "filing_date": "2026-01-29", "value": "$143.8 billion", "period": "Q1 2026", "commentary": "Up 16% year-over-year, a best-ever quarter." }, { "id": "a9f1c2d3-...", "metric": "Revenue", "type": "financial", "filing_date": "2025-01-30", "value": "$124.3 billion", "period": "Q1 2025", "commentary": null } ], "meta": { "after": null, "before": null } }
document_summaries

Retrieves the most recent document summaries for a company identified by ticker and country. Summaries are generated from the company's earnings call transcripts and returned newest-first. Each entry contains the summary content along with the source document_id and its filing_date. Supports date range filtering and cursor-based pagination via the after / before cursors.

Input Parameters

Parameter Type Required Description
ticker string required Company ticker symbol (e.g. AAPL)
country string required ISO 3166-1 alpha-2 country code (e.g. US)
date_from string optional Only include summaries whose filing is on or after this date — ISO 8601 (YYYY-MM-DD)
date_to string optional Only include summaries whose filing is on or before this date — ISO 8601 (YYYY-MM-DD)
limit integer optional Results per page. Defaults to 25, max 100
after string optional Opaque cursor for forward pagination (from meta.after of the previous response)
before string optional Opaque cursor for backward pagination (from meta.before of the previous response)

Response Shape

summary is a structured object with the sections business_performance, outlook, changes_from_previous_call, challenges, and opportunities. Legacy plain-text summaries are returned as a string.

{ "data": [ { "id": "7f9a36de-8359-4dca-aeff-2e2dc495350b", "document_id": "171695c9-98c6-40dc-bc39-b4d171308803", "filing_date": "2026-01-29", "summary": { "business_performance": { "narrative_summary": "...", "financial_metrics_table": [ ... ] }, "outlook": { "summary": { "description": "..." }, "highlights": [ ... ] }, "changes_from_previous_call": [ ... ], "challenges": [ ... ], "opportunities": [ ... ] } } ], "meta": { "after": "<opaque_cursor>", "before": null } }
document_topics

Lists the most recent topics discussed in a company's earnings call transcripts, identified by ticker and country. Returns one entry per company-specific topic, newest-first, each with its category, document_count (how many of the company's documents mentioned it), and up to 5 example mentions (the spoken sentences). Use a topic id with the document_topic_mentions tool to page through all of its mentions. Supports date range filtering and cursor-based pagination.

Input Parameters

Parameter Type Required Description
ticker string required Company ticker symbol (e.g. AAPL)
country string required ISO 3166-1 alpha-2 country code (e.g. US)
date_from string optional Only include topics with a mention on or after this date — ISO 8601 (YYYY-MM-DD)
date_to string optional Only include topics with a mention on or before this date — ISO 8601 (YYYY-MM-DD)
limit integer optional Topics per page. Defaults to 20, max 100
after string optional Opaque cursor for forward pagination (from meta.after of the previous response)
before string optional Opaque cursor for backward pagination (from meta.before of the previous response)

Response Shape

{ "data": [ { "id": "0061f585-aab0-434a-ad5c-3f7b8af116fd", "label": "Paid Subscriptions Growth", "category": "Product", "description": null, "document_count": 3, "mentions": [ { "document_id": "171695c9-98c6-40dc-bc39-b4d171308803", "filing_date": "2026-01-29", "speaker": "Kevan Parekh", "sentences": ["Paid subscriptions also grew double digits."] } ] } ], "meta": { "after": "<opaque_cursor>", "before": null } }
document_topic_mentions

Lists all mentions of a single topic across a company's earnings call transcripts. Use the topic_id of any entry returned by document_topics to page through every mention (the spoken sentences) of that topic for the company, ordered from most recent to oldest. Supports date range filtering and cursor-based pagination.

Input Parameters

Parameter Type Required Description
topic_id string required UUID of a topic returned by document_topics
ticker string required Company ticker symbol (e.g. AAPL)
country string required ISO 3166-1 alpha-2 country code (e.g. US)
date_from string optional Start of date range — ISO 8601 format (YYYY-MM-DD)
date_to string optional End of date range — ISO 8601 format (YYYY-MM-DD)
limit integer optional Mentions per page. Defaults to 20, max 100
after string optional Opaque cursor for forward pagination
before string optional Opaque cursor for backward pagination

Response Shape

{ "data": [ { "document_id": "171695c9-98c6-40dc-bc39-b4d171308803", "filing_date": "2026-01-29", "speaker": "Kevan Parekh", "sentences": ["Paid subscriptions also grew double digits."] } ], "meta": { "after": "<opaque_cursor>", "before": null } }
superanalyst_questions_list

Lists active SuperAnalyst questions for a company identified by ticker and country. Returns questions grouped by category (Market, Business Performance, Unit Economics, Competition, Accounting, Insider Behavior, Challenges, Opportunities). Each entry includes a 1-based display order, a stable id (UUID), the question text, and a why_important explanation. Pass the id to superanalyst_research_plan to retrieve the full research plan — order is a display label only and must not be used as a selector.

Input Parameters

Parameter Type Required Description
ticker string required Company ticker symbol (e.g. AAPL)
country string required ISO 3166-1 alpha-2 country code (e.g. US)

Response Shape

{ "data": [ { "category": "Business Performance", "questions": [ { "order": 1, "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "question": "...", "why_important": "..." } ] } ] }
superanalyst_research_plan

Returns the research plan for a single SuperAnalyst question selected by its stable id. Use superanalyst_questions_list first to retrieve available questions and their id values. Pass the id from the question the user referred to — order is a display label only. If the requested id is no longer present (question archived or replaced), re-list to get current questions.

Input Parameters

Parameter Type Required Description
ticker string required Company ticker symbol (e.g. AAPL)
country string required ISO 3166-1 alpha-2 country code (e.g. US)
id string required Stable UUID of the question, from superanalyst_questions_list

Response Shape

{ "question": "...", "category": "Business Performance", "plan": "...", "unit_economic_variables": ["...", "..."], "actions": ["...", "..."] }
superanalyst_monitoring_plan

Returns the SuperAnalyst monitoring plan for a company identified by ticker and country. The plan groups KPIs into sales, costs, and optionally other_key_metrics. Each KPI includes a list of monitoring methods with a name and rationale (why). Use this to understand how to track key business drivers ahead of earnings.

Input Parameters

Parameter Type Required Description
ticker string required Company ticker symbol (e.g. AAPL)
country string required ISO 3166-1 alpha-2 country code (e.g. US)

Response Shape

{ "data": { "plan": { "sales": [ { "kpi_name": "Global Paid Memberships", "methods": [ { "name": "Credit Card Transaction Analysis", "why": "Track subscriber payment patterns" } ] } ], "costs": [ { "kpi_name": "Content Spend", "methods": [ { "name": "Production Activity Monitoring", "why": "Track production volume and costs" } ] } ], "other_key_metrics": [ { "kpi_name": "User Engagement", "methods": [ { "name": "Content Release Tracking", "why": "Monitor content availability and engagement" } ] } ] }, "updated_at": "2026-01-15T10:30:00Z" } }
key_debates_list

Lists key debates (bull/bear cases) for a company identified by ticker and country. Returns a lightweight summary of each debate — title, description, 1-based order, and generated_at timestamp. Use key_debates_detail with a debate's order to retrieve the full bull/bear cases and supporting evidence.

Input Parameters

Parameter Type Required Description
ticker string required Company ticker symbol (e.g. AAPL)
country string required ISO 3166-1 alpha-2 country code (e.g. US)

Response Shape

{ "data": [ { "title": "...", "description": "...", "order": 1, "generated_at": "2026-01-15T10:30:00Z" } ] }
key_debates_detail

Returns the full bull/bear debate for a single key debate selected by its order. Use key_debates_list first to retrieve available debates and their order values. The order field is 1-based and may shift between regenerations — if the requested order is no longer present, re-list to get current debates.

Input Parameters

Parameter Type Required Description
ticker string required Company ticker symbol (e.g. AAPL)
country string required ISO 3166-1 alpha-2 country code (e.g. US)
order integer required 1-based debate order from key_debates_list

Response Shape

{ "title": "...", "description": "...", "bull_case": "...", "bull_evidence": ["...", "..."], "bear_case": "...", "bear_evidence": ["...", "..."], "order": 1, "generated_at": "2026-01-15T10:30:00Z", "metadata": {} }

Supported Markets

Global public equity markets.

When a query returns zero results, the response includes a meta.coverage object with a hint field. This makes the empty-result state unambiguous — an AI agent can surface the hint directly rather than silently treating the absence of data as a confirmed lack of flags. When a date range was active, the hint distinguishes between "no flags in this window" and "no flags at all", so agents do not draw incorrect conclusions about coverage.

Data Freshness

Data is updated daily.

Rate Limits

Limit 120 requests per minute per access token
Exceeded HTTP 429 Too Many Requests with a Retry-After header

Connect with Claude

The Canary Data MCP server supports the Streamable HTTP transport and authenticates via OAuth 2.0. Connect it to Claude using one of the methods below.

MCP server URL

https://api.canary-data.com/mcp

Claude.ai — Team & Enterprise

Navigate to the connectors page and add the Canary Data MCP server using the URL above.

Claude Desktop — Free & Pro

From Claude settings > Connectors, add a new connector and enter the MCP server URL above. Claude will guide you through the OAuth login flow on first connection.

Claude Code

claude mcp add --transport http canary-data https://api.canary-data.com/mcp

Then run /mcp in your Claude Code session to complete the OAuth authentication flow.

Authentication

Protocol OAuth 2.0 with PKCE (RFC 7636) — authorization code flow
Authorization GET /authorize
Token endpoint POST /token
MCP transport Streamable HTTP at https://api.canary-data.com/mcp, Bearer token required
Access token TTL 1 hour
Refresh token TTL 30 days (rotating)
Discovery /.well-known/oauth-authorization-server