Consensus Analytics MCP server documentation

01Before you connect

A Consensus Analytics account with an active Pro subscription. The 14-day free trial counts. See plans.
An AI client that supports remote MCP servers over Streamable HTTP with OAuth sign-in, such as Claude, Claude Code, ChatGPT or Codex.
For live Excel formulas: desktop Excel with the Consensus Excel add-in installed and signed in.

The server is part of Pro, and the reasoning runs in your own AI, so it uses no Consensus AI credits.

02Connect Claude

Claude on the web and in the desktop app, and Claude Code. If Consensus Analytics is listed in Claude's connector directory, you can add it from there instead of by URL.

Claude (claude.ai and Claude Desktop)

Open Customize → Connectors (claude.ai/customize/connectors).
Add a custom connector, name it Consensus Analytics, and paste the server URL.
Click Connect and sign in with your Consensus Analytics account.
In a chat, turn the connector on from + → Connectors.

On Team and Enterprise plans an Owner may need to add the connector for the organization first.

Claude Code

claude mcp add --transport http consensus https://ai.consensus-analytics.com/mcp

Then run /mcp inside Claude Code, choose consensus, and sign in in the browser window that opens.

03Connect ChatGPT and Codex

ChatGPT on the web and in the desktop app, and Codex in the terminal, the IDE extension and the ChatGPT desktop app. Both sign in to your Consensus Analytics account; there is no API key to copy.

ChatGPT

Open Plugins (chatgpt.com/plugins), select +, then Add custom MCP server.
Enter a name, such as Consensus Analytics, and a short description.
Paste the server URL and choose OAuth authentication. Review the risk warning and select I understand and want to continue.
Select Create as a plugin, sign in with your Consensus Analytics account, and check that the tools are listed.
Start a new conversation, type @ and pick the plugin.

Your ChatGPT plan and workspace policies decide whether you can add custom MCP servers. In a company workspace, an admin may need to allow them first.

Codex

The Codex CLI, the IDE extension and the ChatGPT desktop app share one MCP configuration, so adding the server once makes it available in all three. Add it, then sign in:

codex mcp add consensus --url https://ai.consensus-analytics.com/mcp
codex mcp login consensus

codex mcp login opens a browser to sign in. On a machine without a browser, add --no-browser, open the printed link on another device, and paste the redirect URL back into the terminal. Check the connection with codex mcp list, or /mcp inside Codex.

To configure it by hand instead, add this table to Codex's config.toml and then run codex mcp login consensus:

[mcp_servers.consensus]
url = "https://ai.consensus-analytics.com/mcp"

OpenAI API

The Responses API's mcp tool can call the server with server_url set to the server URL. It doesn't sign in for you: the authorization field must carry an OAuth access token for a Consensus Analytics account, sent with every request, and your application obtains that token through the OAuth flow in the server's metadata (see Authentication and privacy).

{
  "type": "mcp",
  "server_label": "consensus",
  "server_url": "https://ai.consensus-analytics.com/mcp",
  "authorization": "<OAuth access token>"
}

By default the API asks for approval before each tool call. To work with Consensus data interactively, ChatGPT or Codex is simpler.

04Other MCP clients

Point the client at the server URL with the Streamable HTTP transport. It finds the sign-in flow in the server's OAuth metadata and registers itself, so there is no client ID or secret to enter. See Authentication and privacy.

To call the tools directly, use MCP Inspector with the Via Proxy connection type:

npx @modelcontextprotocol/inspector

05Tools

All 12 tools only read Consensus Analytics data. Each one is annotated readOnlyHint: true, destructiveHint: false and openWorldHint: false.

Figures

search_tickers
get_periods
resolve_parameters
get_facts

Filing text

search_filings
get_filing_content

Tool	What it does
Companies and figures
Search Tickers`search_tickers`	Finds a company's canonical ticker, such as `AAPL.US`, by symbol or name.
Get Reporting Periods`get_periods`	Lists the annual (`FY2024`) and quarterly (`1Q2024`) periods available for a company.
Resolve Report Lines`resolve_parameters`	Matches metric names such as "Revenue" or "Operating Margin" to the exact report lines in the company's filings, with a source link for each.
Get Financial Facts`get_facts`	Returns values for several report lines and periods in one call, each with a link to its source.
Excel formulas
Build CaData Formula Block`build_cadata_block`	Builds a grid of live `=CaData()` formulas, one row per report line and one column per period.
Build Report Schedule`build_report_schedule`	Reproduces a whole statement, such as the income statement, as live formulas in the filing's own line order.
Filings
Search Filings`search_filings`	Searches the full text of indexed filings, filtered by company, form type and filing date. Returns matching snippets and a source link.
Read Filing Content`get_filing_content`	Reads a filing's text, jumping to the passages that match a query.
Playbooks
List Skills`list_skills`	Lists the analysis playbooks with a short description of each.
Get Skill`get_skill`	Loads a playbook's full method: the tools it uses, the steps and the output format.
Search and fetch
Search Consensus`search`	Finds companies, filings and playbooks by free-text query. Used by retrieval-style clients.
Fetch Document`fetch`	Opens a company profile, a filing's text or a playbook from a search result.

06Live Excel formulas

build_cadata_block and build_report_schedule return formulas instead of static numbers. Paste them into a workbook and they pick up the next filing.

=CaData("TICKER","PERIOD","REPORT_LINE",,UNITS)

Argument	Value
`TICKER`	The canonical ticker from `search_tickers`, such as `AAPL.US`.
`PERIOD`	`FY2024` for a fiscal year, `1Q2024` for a quarter.
`REPORT_LINE`	The exact report-line name from `resolve_parameters` or the statement's own line.
`UNITS`	`0` as reported, `1` single, `2` thousands, `3` millions.

The formulas refresh in desktop Excel with the Consensus add-in installed and signed in, for you and for colleagues who open the workbook. Anywhere else they show #NAME?. get_facts returns the same values as static numbers.

07Analysis playbooks

A playbook is a written method for one kind of analysis: which tools to call, in what order, and what the output should look like. Your AI finds one with list_skills, loads it with get_skill, and runs it on Consensus data.

Playbooks are also served as MCP prompts and as MCP resources at skill://consensus/{name}/SKILL.md. Every playbook follows a shared set of conventions for ticker and metric resolution, provenance, units, periods and missing data, served as conventions. To run one, name it in your prompt, for example "Run the earnings review playbook on Microsoft's latest quarter."

Company overview 3

Business Model Summarybusiness_model_summary
Explains how a company actually makes money — revenue mechanics grounded in the filings, not marketing copy.
Company Primer / Initiation Reportcompany_primer
Initiation-style report on a company for an analyst new to the name: business model, segments, multi-year historicals, capital structure, risks, and recent developments.
Quick Snapshotquick_snapshot
One-screen fact card: scale, growth, margins, FCF, and net debt at a glance.

Earnings & guidance 4

Earnings Reviewearnings_review
Post-print review of a reported quarter: headline numbers, segment walk, guidance changes, and one-time items — the quarter in three minutes.
Guidance vs. Actuals Trackerguidance_tracker
Multi-year ledger of management guidance versus reported actuals — beat/met/missed with magnitudes and revision behavior.
KPI Trend Reviewkpi_trend_review
Sector-appropriate KPI trajectory over a multi-quarter window, with acceleration/deceleration and inflection detection.
Pre-Earnings Prep Sheetpreprint_prep
Night-before-the-print prep sheet: trend heading in, standing guidance, management's guide track record, and peer read-through.

Financial quality 6

Forensic Red-Flag Scanred_flag_scan
Full forensic battery on a company: M-Score, F-Score, Z-Score, accruals quality, and drift flags — with the underlying evidence for everything elevated.
Going Concern & Liquidity Scangoing_concern_scan
Binary-first scan: is there substantial-doubt language anywhere recent — and if not, how far away is the nearest yellow flag?
Related-Party Transaction Scanrelated_party_scan
Catalogs related-party transactions from 10-K notes and proxy statements: counterparties, amounts, trends, and terms — ranked by analyst concern.
Restatement Historyrestatement_history
Restatements and revisions over a multi-year window: "Big R" non-reliance restatements vs. "little r" revisions, with causes, magnitudes, and patterns.
Revenue Quality Scanrevenue_quality_scan
How much of reported revenue is backed by cash, and are the accrual bridges behaving? Cash conversion, billings, backlog conversion, and receivable-monetization checks.
Working Capital Qualityworking_capital_quality
DSO/DIO/DPO trend analysis with growth-divergence checks: is working capital moving with the business, or is something being stuffed or stretched?

Change detection 7

Accounting Policy Diffaccounting_policy_diff
Diffs the Summary of Significant Accounting Policies between 10-Ks: voluntary changes, standard adoptions, and estimate changes — each labeled by type.
Adj. Metric Definition Diffadj_metric_definition_diff
Tracks how an issuer's Adj. metric definition changes over time: addbacks introduced or dropped, recurring "one-timers," and adjustment intensity.
Auditor & Control Issues Scanauditor_change_scan
Fast scan for auditor changes, non-reliance events, and internal-control weaknesses — evidence-linked, with remediation tracking.
MD&A Diff (YoY)mda_diff
Year-over-year diff of the MD&A narrative: driver-attribution changes, liquidity-tone shifts, and critical-estimate changes.
Revenue Recognition Policy Diffrevenue_recognition_diff
Compares revenue recognition disclosures across 10-Ks: performance obligations, timing, variable consideration, principal-vs-agent, disaggregation, and contract balances.
Risk Factor Diff (YoY)risk_factor_diff
Year-over-year diff of Item 1A Risk Factors: what management newly fears, what they stopped worrying about, and what changed in the fine print — ranked by materiality.
Segment Reporting Diffsegment_reporting_diff
Detects segment redefinitions between fiscal years: renames, recompositions, measure changes, and what visibility was gained or lost.

Disclosure deep-dives 5

Cybersecurity Disclosure Reviewcybersecurity_disclosure_review
Cyber posture as disclosed: incident 8-Ks, Item 1C governance, cost follow-through, and hypothetical-to-experiential risk-language shifts.
Deferred Revenue & RPO Walkdeferred_revenue_walk
The forward-revenue signal chain: bookings → deferred revenue/RPO → recognized revenue, with conversion rates and mix-shift signals.
Legal Proceedings Reviewlegal_proceedings_review
Matter-level litigation register with quarter-by-quarter language-escalation tracking — disclosure language shifts precede charges.
Pension & OPEB Analysispension_obligation_analysis
Defined-benefit pension and OPEB analysis: funded status, assumption honesty, and the earnings-versus-cash picture.
Segment Reconciliationsegment_reconciliation
Per-segment P&L rebuilt from the segment disclosure lines and reconciled to consolidated — with the tie-out check shown.

Corporate actions & capital structure 4

Capital Allocation Reviewcapital_allocation_review
Multi-year sources-and-uses of capital: where the cash came from, where it went, and whether the buyback math actually reduced the share count.
Debt Structure & Maturity Ladderdebt_maturity_ladder
Instrument-level debt picture: the maturity wall, covenants, rate exposure, and liquidity coverage against upcoming maturities.
M&A History & Integration Track Recordma_history
Reconstructs a company's acquisition history: what they bought, what they paid, goodwill created, and what happened to each deal afterward.
Recent 8-K Digestrecent_8k_digest
Catch-up briefing: every 8-K in a window, classified by item type and summarized — what happened while you weren't looking.

Governance & compensation 3

Board Composition Reviewboard_composition_review
Board profile from the proxy: roster, independence, tenure, committee structure, and turnover versus the prior year.
Executive Compensation Reviewexecutive_comp_review
NEO pay, incentive design, and alignment flags from the proxy: is management paid to do what shareholders want done?
Say-on-Pay Historysay_on_pay_history
Say-on-Pay vote results over time and whether the comp committee's announced responses actually showed up in the next proxy.

Peer & screening 3

Competitive Positioning Mappositioning_map
Chart-ready positioning data for a peer set: growth vs. margin vs. scale, plus a written quadrant read.
Peer Comparison / Comp Tablepeer_comparison
Comp table across up to 25 tickers: metrics × periods with medians and ranks, plus an optional live-formula Excel tab.
Universe Screeneruniverse_screener
Screens a candidate universe against structured metric thresholds and qualitative filings-text conditions, with every company accounted for.

Sector walks 6

Bank Credit & Margin Walkbank_credit_walk
NIM trajectory, the provision/charge-off/reserve credit triangle, capital ratios, and funding — the full bank operating picture.
E&P Production & Netback Walkenergy_production_walk
Production by stream, realized prices, per-boe cost structure, netbacks, reserves, and capital efficiency for exploration & production names.
Insurance Underwriting Walkinsurance_underwriting_walk
Combined-ratio bridge, reserve development, premium growth, and float economics for insurance names.
REIT NOI & FFO Walkreit_noi_walk
Same-store NOI, occupancy, releasing spreads, FFO/AFFO, dividend safety, and external growth for REITs.
Retail Comps Walkretail_comps_walk
Comps stacks, traffic-versus-ticket decomposition, unit growth, productivity, and inventory discipline for retail names.
SaaS Metrics Walksaas_metrics_walk
ARR family, retention, RPO, billings, Rule of 40, and Magic Number — the full SaaS operating picture over a multi-quarter window.

Modeling & Excel 3

Historical Model Seed (3-Statement)historical_model_seed
Seeds a 3-statement historical model: every line of the Income Statement, Balance Sheet, and Cash Flow as live =CaData() formulas, in the issuer's own filing structure.
Provenance-Footnoted Exportprovenance_footnoted_export
Metric grid with per-cell source footnotes: every cell answers "where did this number come from?" — for investment committees, PM review, or compliance.
Standardized Statement Exportstandardized_statement_export
Statement export as a live-formula block in the issuer's own filing structure: every line, in filing order.

list_skills always returns the current set.

08Example prompts

Try these once the connector is on. Your AI picks the tools; the ones listed are what it typically calls.

01

Pull Apple's revenue, operating income and free cash flow for FY2022 to FY2024, with a source link for each number.

Uses search_tickers get_periods resolve_parameters get_facts
02

What changed in Boeing's risk factors between its two most recent 10-Ks?

Uses search_tickers search_filings get_filing_content
03

Find 8-K filings from the last six months that disclose a material weakness, and summarize each one.

Uses search_filings get_filing_content
04

Build Microsoft's income statement for FY2021 to FY2024 as live =CaData formulas I can paste into Excel.

Uses search_tickers get_periods build_report_schedule
05

Run a forensic red-flag scan on NVIDIA.

Uses get_skill search_tickers get_periods resolve_parameters get_facts
06

What were NVIDIA's revenue and net income in each of its last four fiscal years?

Uses search_tickers get_periods resolve_parameters get_facts
07

Show NVIDIA's quarterly revenue for the last eight quarters, with a source link for each number.

Uses search_tickers get_periods resolve_parameters get_facts
08

Give me live =CaData formulas for NVIDIA's revenue and net income for FY2024 to FY2026.

Uses search_tickers resolve_parameters build_cadata_block
09

What does Apple's most recent 10-K say about its manufacturing in China? Quote the passages.

Uses search_tickers search_filings get_filing_content
10

Which companies mentioned tariff refunds in 8-K filings over the last 30 days? Summarize what each one said.

Uses search_filings get_filing_content
11

Run the earnings review playbook on NVIDIA's latest quarter.

Uses get_skill get_periods resolve_parameters get_facts search_filings get_filing_content
12

What analysis playbooks does Consensus offer?

Uses list_skills
13

Search Consensus for Boeing and open its company profile.

Uses search fetch

09Data coverage and limits

Coverage is 7,000+ US companies that file with the SEC. Structured values come from 10-K, 10-Q and 8-K filings, plus 20-F, 40-F and 6-K filings from foreign private issuers.
Full-text search also covers other indexed filings, such as proxy statements and registration statements.
New filings typically reach Consensus within minutes of EDGAR.
Quarterly values are shown as filed where the issuer discloses the quarter, and derived otherwise, for example Q4 as the full year minus the first nine months.
Long filings come back in sections. Ask for a specific section or phrase to reach the rest.
Source links open in the Consensus Analytics web app and need you to be signed in.
=CaData() formulas refresh only in desktop Excel with the Consensus add-in signed in.

10Authentication and data handling

Sign-in uses OAuth 2.1 with PKCE against https://auth.consensus-analytics.com. Clients register themselves through dynamic client registration, and your AI client never sees your password.
Tool calls need the mcp scope, which accounts with an active subscription or trial are granted.
An unauthenticated request gets HTTP 401 with a WWW-Authenticate header pointing to the protected resource metadata at https://ai.consensus-analytics.com/.well-known/oauth-protected-resource/mcp.
Requests to /mcp that carry a browser Origin header from another site are rejected with HTTP 403, as protection against DNS rebinding.
What reaches Consensus is the tool name and its arguments: tickers, periods, report-line names, search phrases and document ids. Your conversation, files and workbooks are not sent.
Requests may be logged to operate and secure the service. See the Privacy Policy and Security & compliance.

11Troubleshooting

Every tool replies that an active subscription is required.: The signed-in account has no active subscription or trial. Start one, then disconnect and reconnect the connector so the new access applies.
The client can't connect, or sign-in fails.: Check that the URL is exactly https://ai.consensus-analytics.com/mcp, then remove the connector and add it again.
ChatGPT doesn't offer Add custom MCP server.: Custom MCP servers depend on your ChatGPT plan and workspace policies. In a company workspace, ask an admin to allow them.
Codex shows the server as needing sign-in.: Run codex mcp login consensus and sign in with your Consensus Analytics account.
MCP Inspector gets HTTP 403.: The Inspector is connecting straight from the browser, which sends an Origin header. Switch the connection type to Via Proxy.
Excel shows #NAME?.: Install the Consensus Excel add-in in desktop Excel and sign in.
A source link asks me to sign in.: Source links open in the Consensus Analytics web app. Sign in with the same account you connected.

12Support

Help and questions

Use the contact form in the Help Center.

Plans and enterprise access

sales@consensus-analytics.com