Valuein MCP Server
Built for AI agents. 49 structured tools and 22 agentic workflows over 105M+ SEC EDGAR facts. Streamable HTTP transport, bearer-token auth, edge-computed at mcp.valuein.biz/mcp.
https://mcp.valuein.biz/mcpQuick Setup
Pick your client, paste the config, replace YOUR_TOKEN, restart. Tokens are provisioned on the pricing page — the S&P500 tier is free.
Edit the config file, then restart Claude Desktop. Settings → Developer → Edit Config opens it directly.
Tip: Omit --headers to use the free sample tier.
%APPDATA%\Claude\claude_desktop_config.json{
"mcpServers": {
"valuein": {
"url": "https://mcp.valuein.biz/mcp",
"headers": {
"Authorization": "Bearer YOUR_TOKEN_HERE"
}
}
}
}Authentication
Every request carries Authorization: Bearer <token>. Tokens are stored as hashes in Cloudflare KV and validated at the edge — no round-trip to origin.
- • 64-char hex, scoped to a single tier
- • Rotatable in the dashboard
- • Revocation propagates in <60s globally
- • Sample tier also works without a token (IP-scoped)
Rate Limits by Tier
Limits are enforced per-token at the Cloudflare edge. On throttle, the server returns 429 with a Retry-After header.
| Tier | Per minute | Per hour | Notes |
|---|---|---|---|
| Sample (free, no token) | 15 req/min | 150/hr | Shared guest quota, IP-scoped. |
| Free (token required) | 60 req/min | 1,000/hr | Token provisioned at signup. |
| Pro | 100 req/min | 3,000/hr | Full 17K+ ticker universe, 30yr history. |
| Institutional | 300 req/min | 10,000/hr | Adds foreign issuers, intraday, webhooks, redistribution. |
| Enterprise | Negotiable | Negotiable | Dedicated workers, private routing, custom SLA. |
Error codes
Every error includes a structured JSON body with code, message, and hint. Your agent should read the hint before retrying.
401Missing or malformed Authorization header.
Send 'Authorization: Bearer <token>'. Token must be 64 hex chars.
403Token is valid but lacks access to this tool or data scope.
Upgrade tier or confirm the tool is listed in your plan.
404Ticker or fact_id not found in the current tier's universe.
For sample tier, only S&P500 companies resolve; upgrade for broader coverage.
422Input failed schema validation (zod).
Check argument types and formats — e.g. dates must be YYYY-MM-DD.
429Rate limit exceeded for this token.
Back off and retry after the 'Retry-After' header seconds.
503Upstream Parquet fetch failed (rare).
Retry with exponential backoff; the R2 read will usually succeed on second try.
Tools (49)
Discrete, typed actions. Each returns structured JSON with a _meta block that your agent can use to cite sources and determine freshness.
search_companiesSearch Companies
Search for companies by name, ticker symbol, or CIK.
get_company_fundamentalsCompany Fundamentals
Core financial statement data for a company: income statement, balance sheet, and cash flow metrics per fiscal period.
get_valuation_metricsValuation Metrics
Merged valuation data from fact.
get_financial_ratiosFinancial Ratios
Pipeline-computed derived financial ratios from ratio.
get_sec_filing_linksSEC Filing Links
Retrieve SEC EDGAR filing URLs for a company.
get_capital_allocation_profileCapital Allocation Profile
Capital allocation breakdown per fiscal period: operating cash flow, capex, free cash flow, dividends paid, share repurchases, debt issuance, and debt repayment.
get_peer_comparablesPeer Comparables
Cross-sectional peer comparison using pipeline-computed financial ratios.
get_pit_universePoint-in-Time Universe
Returns the exact set of active companies as of a specific historical date.
get_compute_ready_streamCompute-Ready Stream
Returns a presigned R2 URL for direct bulk Parquet access.
describe_schemaDescribe Data Schema
Returns the Parquet schema for all tables in the Valuein SEC data warehouse: table descriptions, column names, types, primary keys, and foreign-key references.
verify_fact_lineageVerify Fact Lineage
Verify the provenance of a financial data point by its deterministic fact_id hash.
compare_periodsCompare Financial Periods
Compare a company's core financial metrics across two fiscal periods side-by-side.
screen_universeScreen Universe by Factor Scores
Cross-sectional factor screening using pipeline-computed percentile ranks.
get_earnings_signalsEarnings Signals
Trend-based earnings expectations and surprise metrics.
search_filing_textSearch Filing Text
Semantic search over SEC 10-K and 10-Q narrative sections — Risk Factors, MD&A, Business, Legal Proceedings, and Controls & Procedures.
get_insider_transactionsInsider Transactions
MCP tool: get_insider_transactions.
get_institutional_holdingsInstitutional Holdings (by issuer)
MCP tool: get_institutional_holdings.
get_manager_portfolioManager Portfolio (13F by filer)
MCP tool: get_manager_portfolio.
get_blockholdersBlockholders (SC 13D / 13G)
MCP tool: get_blockholders.
get_insider_sentimentInsider Sentiment (composite)
MCP tool: get_insider_sentiment.
get_top_holdersTop Holders (composite, classified)
MCP tool: get_top_holders.
get_smart_money_flowSmart Money Flow (composite)
MCP tool: get_smart_money_flow.
save_thesisSave Investment Thesis
MCP tool: save_thesis.
list_thesesList Saved Theses
MCP tool: list_theses.
get_thesisGet Saved Thesis
Fetch a single saved thesis by its id.
delete_thesisArchive Saved Thesis
Soft-delete a saved thesis: status flips to `archived` (the row stays for audit / re-scoring).
score_thesis_outcomeScore Thesis Outcome
Grade a saved thesis against fundamental momentum since its creation.
save_watchlistSave Watchlist
Upsert a named watchlist with a list of tickers.
list_watchlistsList Watchlists
MCP tool: list_watchlists.
get_watchlistGet Watchlist
Fetch a single watchlist by name.
delete_watchlistArchive Watchlist
Soft-delete: status flips to `archived`.
watchlist_diffWatchlist Diff
MCP tool: watchlist_diff.
create_alertCreate Alert
MCP tool: create_alert.
list_alertsList Alerts
MCP tool: list_alerts.
delete_alertDelete Alert
Soft-delete: status flips to `deleted`.
test_alertTest Alert (synthetic fire)
MCP tool: test_alert.
list_alert_inboxList Alert Inbox
MCP tool: list_alert_inbox.
mark_inbox_readMark Inbox Item Read
Set `read_at` on a single inbox item.
dismiss_inbox_itemDismiss Inbox Item
Soft-delete an inbox item — sets `dismissed_at`.
create_reportCreate Research Report
MCP tool: create_report.
get_reportGet Research Report
Fetch a report by id.
list_my_reportsList My Research Reports
MCP tool: list_my_reports.
delete_reportDelete (Soft) Research Report
Soft-delete a report owned by the caller: status flips to `delisted`, visibility to `private`.
compute_dcfCompute Forward DCF
Forward discounted-cash-flow valuation: caller provides growth + WACC + terminal assumptions, returns per-share intrinsic value + 5×5 sensitivity grid.
forensic_auditForensic Audit (Beneish + Sloan + Solvency)
MCP tool: forensic_audit.
update_reportUpdate Report Sections
MCP tool: update_report.
generate_dcf_xlsxGenerate DCF Workbook (xlsx)
Render a forward DCF result into a professional Excel workbook (Summary + 5×5 Sensitivity heatmap + Inputs sheet).
generate_research_brief_docxGenerate Research Brief (docx)
Render a structured research brief into a professionally-styled Word document — cover, abstract, optional snapshot table, body sections, and a citations table with clickable SEC EDGAR links.
generate_comps_xlsxGenerate Peer Comparables Workbook (xlsx)
Render a peer comparables table into an Excel workbook.
Agentic Prompts (22)
Prompts are multi-step Standard Operating Procedures — pre-wired chains of tool calls that a senior analyst, quant, or PM would run to produce institutional-quality analysis. Your agent calls one prompt, the server returns a structured plan, and the agent executes the tool chain in the correct order.
equity_research_briefEquity Research Brief
Single-ticker end-to-end institutional research brief in markdown — fundamentals, valuation, ratios, capital allocation, peer comparison, recent catalysts, and SEC lineage. Three depth modes: 'quick' (≈3 tool calls — snapshot), 'full' (≈8 calls — default institutional brief), 'forensic' (≈11 calls — adds restatement audit + fact-level SEC verification). Renders as an artifact users can export to Word/PDF directly from Claude Desktop or claude.ai. PIT-safe via as_of_date for backtests.
screen_and_shortlistScreen and Shortlist
PM idea-generation workflow. Builds a survivorship-free universe via index_membership.parquet, ranks it on a chosen factor objective (quality, value, growth, or balanced), QCs the top 3 with a period-over-period change check, and hands off shortlist members to equity_research_brief for full write-ups. Renders as a markdown shortlist artifact. Survivorship-free historical screening via as_of_date.
sector?index?objective?as_of_date?top_n?margin_and_moat_teardownMargin & Moat Teardown
Systematic 5-year analysis of a company's operational efficiency and competitive moat. Chains fundamentals → valuation metrics → peer comparables to produce a structured teardown covering revenue quality, margin trends, ROIC vs WACC spread, and relative positioning vs sector peers.
peer_benchmarking_memoPeer Benchmarking Memo
Produces a structured relative-value memo comparing a company to its closest peers. Chains search_companies → peer_comparables → valuation_metrics → financial_ratios to output an investment-committee-ready comparison table with ROIC, valuation multiples, and capital efficiency.
quality_and_risk_auditQuality & Risk Audit
Evaluates capital structure safety and dividend sustainability for portfolio risk-adjusted sizing. Chains fundamentals → capital_allocation → valuation_metrics → financial_ratios (leverage/liquidity) to produce a structured risk scorecard.
capital_allocation_reviewCapital Allocation Review
Evaluates management's capital allocation decisions over a multi-year period. Chains capital_allocation_profile → valuation_metrics → financial_ratios to produce a management-quality scorecard: does management create value with retained earnings?
tickersurvivorship_free_backtestSurvivorship-Free Backtest
Sets up a bias-free quantitative backtest by defining the historical universe and providing Parquet URLs for bulk data access. Chains get_pit_universe → get_compute_ready_stream to produce ready-to-run Python/DuckDB code.
start_dateend_datepit_factor_constructorPoint-in-Time Factor Constructor
Guides construction of a quantitative factor (Quality, Value, Momentum) across a sector universe using ratio.parquet data. Chains get_pit_universe → get_financial_ratios → get_compute_ready_stream to produce normalized factor scores.
factor_typeratio_deep_diveRatio Deep Dive
Comprehensive ratio profile for a single company spanning all 7 ratio categories (profitability, liquidity, leverage, efficiency, per_share, owner_earnings, valuation). Includes TTM and 5-year annual history with trend analysis.
tickersector_ratio_screenSector Ratio Screen
Cross-sectional ratio ranking across a sector to surface the highest-quality or best-value companies. Chains get_pit_universe → get_compute_ready_stream to screen the full sector using pipeline-computed ratios.
sectorscreen_typesmart_money_briefSmart Money Brief
Single-ticker smart-money brief: composite flow score, top holders (classified), 13F deltas, blockholder alerts, and insider sentiment overlay. Three depth modes: 'quick' (3 composites only), 'standard' (default, + 13F + blockholders), 'deep' (+ insider transactions + company fundamentals for fundamental context). Renders as an exportable markdown artifact. Institutional tier only.
activist_surveillanceActivist Surveillance
Event-driven surveillance for activist target / takeover candidates. Surfaces filers flipping 13G → 13D within the lookback window (the strongest activist signal in the dataset), then cross-references defensive insider activity and 8-K item 1.01 filings to check whether a corporate response is already in motion. Banker / event-driven desk workflow. Institutional tier only.
tickerlookback_days?forensic_earnings_briefForensic Earnings-Quality Brief
Hedge-fund-grade earnings-quality red-flag brief for a single ticker. Chains forensic_audit (deterministic Beneish M + Altman Z' + Sloan accruals) → restatement diff → Risk-Factor delta to surface fraud / quality concerns. Output: structured red-flag list with citation to specific XBRL tags + 10-K accessions.
smart_money_pulseSmart-Money Pulse
PM digest: 13F + insider activity across the caller's watchlist. Surfaces top fund accumulators, recent insider clusters, and 13D/13G activist filings worth investigating. Institutional tier (full plan) only.
watchlist_namelookback_daysmorning_briefingMorning Briefing
Daily overnight digest: material SEC filings across the caller's watchlist since the last close. Ranks by likely impact (M-score change candidates, 8-K item types, amendment flags).
watchlist_namesinceearnings_pulseEarnings Pulse
Pre-earnings pulse for a single ticker. Pulls last 8 quarters of fundamentals + the existing get_earnings_signals trend + management-credibility cross-check (promise-vs-delivery on key segments). Output: 1-page pre-read for an analyst attending the call.
restatement_radarRestatement Radar
Daily/weekly sweep for 10-K/A and 10-Q/A amendments across a watchlist (or the caller's full ticker set). Surfaces amendments that materially changed reported revenue, cash flow, or earnings — the highest-signal restatement events for a forensic analyst.
watchlist_namesinceactivist_radarActivist Radar
Detect new SC 13D / 13G filings across the watchlist and pull the activist's historical playbook stats. Surfaces 13G→13D conversions (the strongest 'going active' signal). Institutional tier.
watchlist_namelookback_daysscreen_to_thesisScreen → Thesis Pipeline
End-to-end idea-generation pipeline: screen → forensic audit → save thesis for the top N candidates. Produces both the screening result + a saved thesis on each conviction name. Wraps existing screen_universe + forensic_audit + save_thesis.
criteria_namemax_resultsportfolio_health_checkPortfolio Health Check
End-of-week diagnostic on the caller's saved theses: which are still on track (positive directional momentum) vs. broken (signals diverging from view). Runs score_thesis_outcome over the active set and produces a top-3-issues list.
sector_overview_flowSector Overview
Comprehensive sector / industry landscape brief — market dynamics, top 5–10 players, competitive structure, valuation context, and investment debate. Distinct from sector_ratio_screen (which is just a screen) and screen_and_shortlist (single-theme idea generation) — this is full sector context. Adapted from anthropics/financial-services equity-research/sector-overview.
sectordcf_build_flowDCF Build (Disciplined)
Disciplined forward-DCF construction for a single ticker — pulls fundamentals, justifies each assumption against history + peers, calls compute_dcf, and renders the full per-share value + 5×5 sensitivity grid. Wraps Valuein's existing compute_dcf math tool with verify-at-each-step discipline. Adapted from anthropics/financial-services financial-analysis/dcf-model.
tickerPlan Access Matrix
Tools are gated by plan tier. Higher plans unlock all lower-tier tools.
Response Format
Every tool returns structured JSON. Numeric fields are raw SEC-filed values (no scaling, no normalization beyond concept mapping). The _meta block is consistent across all tools — your agent can use it to cite sources or invalidate caches.
accepted_atSEC acceptance timestamp — when this fact became public. Use for PIT reasoning.source_accessionSEC EDGAR accession ID. Concatenate withsec.gov/cgi-bin/browse-edgarfor source link.pit_safeBoolean — true means the response honors the as_of_date filter; false means it reflects the latest snapshot.fact_ids_includedCount of underlying fact rows. Pair withverify_fact_lineagefor audit trails.
Example — get_company_fundamentals response
{
"ticker": "AAPL",
"cik": "0000320193",
"fiscal_year": 2024,
"fiscal_period": "FY",
"period_end": "2024-09-28",
"filing_date": "2024-11-01",
"accepted_at": "2024-11-01T20:42:12Z",
"revenue": 391035000000,
"net_income": 93736000000,
"eps_diluted": 6.11,
"operating_cash_flow": 118254000000,
"capex": -9447000000,
"_meta": {
"source_accession": "0000320193-24-000123",
"pit_safe": true,
"fact_ids_included": 12
}
}See PIT methodology for how accepted_at is sourced and validated.
Developer FAQ
Not building an agent? Use the other surfaces.
Same data, same token, different delivery. Pick the interface that matches your workflow.
Get started with MCP
The S&P500 tier is free — no credit card. Get a token and start querying SEC financial data from Claude, Cursor, or any MCP client today.