MCP Server live — AI agents can now query 105M+ SEC facts. Connect your agent →
ValueinValuein
MCP Developer Reference

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/mcp
Live
49 tools
22 prompts

Quick Setup

Pick your client, paste the config, replace YOUR_TOKEN, restart. Tokens are provisioned on the pricing page — the S&P500 tier is free.

jsonclaude_desktop_config.json

Edit the config file, then restart Claude Desktop. Settings → Developer → Edit Config opens it directly.

Tip: Omit --headers to use the free sample tier.

Path:%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.

TierPer minutePer hourNotes
Sample (free, no token)15 req/min150/hrShared guest quota, IP-scoped.
Free (token required)60 req/min1,000/hrToken provisioned at signup.
Pro100 req/min3,000/hrFull 17K+ ticker universe, 30yr history.
Institutional300 req/min10,000/hrAdds foreign issuers, intraday, webhooks, redistribution.
EnterpriseNegotiableNegotiableDedicated 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.

401

Missing or malformed Authorization header.

Send 'Authorization: Bearer <token>'. Token must be 64 hex chars.

403

Token is valid but lacks access to this tool or data scope.

Upgrade tier or confirm the tool is listed in your plan.

404

Ticker or fact_id not found in the current tier's universe.

For sample tier, only S&P500 companies resolve; upgrade for broader coverage.

422

Input failed schema validation (zod).

Check argument types and formats — e.g. dates must be YYYY-MM-DD.

429

Rate limit exceeded for this token.

Back off and retry after the 'Retry-After' header seconds.

503

Upstream 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_companies
Discovery

Search Companies

Search for companies by name, ticker symbol, or CIK.

sample
sp500
full
get_company_fundamentals
Financials

Company Fundamentals

Core financial statement data for a company: income statement, balance sheet, and cash flow metrics per fiscal period.

sample
sp500
full
PIT-safe
get_valuation_metrics
Valuation

Valuation Metrics

Merged valuation data from fact.

sample
sp500
full
PIT-safe
get_financial_ratios
Financials

Financial Ratios

Pipeline-computed derived financial ratios from ratio.

sample
sp500
full
get_sec_filing_links
Discovery

SEC Filing Links

Retrieve SEC EDGAR filing URLs for a company.

sample
sp500
full
PIT-safe
get_capital_allocation_profile
Financials

Capital Allocation Profile

Capital allocation breakdown per fiscal period: operating cash flow, capex, free cash flow, dividends paid, share repurchases, debt issuance, and debt repayment.

sample
sp500
full
PIT-safe
get_peer_comparables
Analysis

Peer Comparables

Cross-sectional peer comparison using pipeline-computed financial ratios.

sample
sp500
full
get_pit_universe
Universe

Point-in-Time Universe

Returns the exact set of active companies as of a specific historical date.

sample
sp500
full
PIT-safe
get_compute_ready_stream
Bulk Access

Compute-Ready Stream

Returns a presigned R2 URL for direct bulk Parquet access.

sample
sp500
full
describe_schema
Discovery

Describe 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.

sample
sp500
full
verify_fact_lineage
Analysis

Verify Fact Lineage

Verify the provenance of a financial data point by its deterministic fact_id hash.

sample
sp500
full
PIT-safe
compare_periods
Analysis

Compare Financial Periods

Compare a company's core financial metrics across two fiscal periods side-by-side.

sample
sp500
full
PIT-safe
screen_universe
Screening

Screen Universe by Factor Scores

Cross-sectional factor screening using pipeline-computed percentile ranks.

sample
sp500
full
get_earnings_signals
Signals

Earnings Signals

Trend-based earnings expectations and surprise metrics.

sample
sp500
full
PIT-safe
search_filing_text
Discovery

Search Filing Text

Semantic search over SEC 10-K and 10-Q narrative sections — Risk Factors, MD&A, Business, Legal Proceedings, and Controls & Procedures.

sample
sp500
full
PIT-safe
get_insider_transactions
Smart Money

Insider Transactions

MCP tool: get_insider_transactions.

full
PIT-safe
get_institutional_holdings
Smart Money

Institutional Holdings (by issuer)

MCP tool: get_institutional_holdings.

full
PIT-safe
get_manager_portfolio
Smart Money

Manager Portfolio (13F by filer)

MCP tool: get_manager_portfolio.

full
PIT-safe
get_blockholders
Smart Money

Blockholders (SC 13D / 13G)

MCP tool: get_blockholders.

full
PIT-safe
get_insider_sentiment
Smart Money

Insider Sentiment (composite)

MCP tool: get_insider_sentiment.

full
PIT-safe
get_top_holders
Smart Money

Top Holders (composite, classified)

MCP tool: get_top_holders.

full
PIT-safe
get_smart_money_flow
Smart Money

Smart Money Flow (composite)

MCP tool: get_smart_money_flow.

full
PIT-safe
save_thesis
State

Save Investment Thesis

MCP tool: save_thesis.

sp500
full
list_theses
State

List Saved Theses

MCP tool: list_theses.

sp500
full
get_thesis
State

Get Saved Thesis

Fetch a single saved thesis by its id.

sp500
full
delete_thesis
State

Archive Saved Thesis

Soft-delete a saved thesis: status flips to `archived` (the row stays for audit / re-scoring).

sp500
full
score_thesis_outcome
State

Score Thesis Outcome

Grade a saved thesis against fundamental momentum since its creation.

sp500
full
save_watchlist
State

Save Watchlist

Upsert a named watchlist with a list of tickers.

sp500
full
list_watchlists
State

List Watchlists

MCP tool: list_watchlists.

sp500
full
get_watchlist
State

Get Watchlist

Fetch a single watchlist by name.

sp500
full
delete_watchlist
State

Archive Watchlist

Soft-delete: status flips to `archived`.

sp500
full
watchlist_diff
Discovery

Watchlist Diff

MCP tool: watchlist_diff.

sp500
full
create_alert
State

Create Alert

MCP tool: create_alert.

sp500
full
list_alerts
State

List Alerts

MCP tool: list_alerts.

sp500
full
delete_alert
State

Delete Alert

Soft-delete: status flips to `deleted`.

sp500
full
test_alert
State

Test Alert (synthetic fire)

MCP tool: test_alert.

sp500
full
list_alert_inbox
State

List Alert Inbox

MCP tool: list_alert_inbox.

sp500
full
mark_inbox_read
Discovery

Mark Inbox Item Read

Set `read_at` on a single inbox item.

sp500
full
dismiss_inbox_item
Discovery

Dismiss Inbox Item

Soft-delete an inbox item — sets `dismissed_at`.

sp500
full
create_report
Reports

Create Research Report

MCP tool: create_report.

full
get_report
Reports

Get Research Report

Fetch a report by id.

full
list_my_reports
Reports

List My Research Reports

MCP tool: list_my_reports.

full
delete_report
Reports

Delete (Soft) Research Report

Soft-delete a report owned by the caller: status flips to `delisted`, visibility to `private`.

full
compute_dcf
Valuation

Compute Forward DCF

Forward discounted-cash-flow valuation: caller provides growth + WACC + terminal assumptions, returns per-share intrinsic value + 5×5 sensitivity grid.

full
PIT-safe
forensic_audit
Valuation

Forensic Audit (Beneish + Sloan + Solvency)

MCP tool: forensic_audit.

full
PIT-safe
update_report
Reports

Update Report Sections

MCP tool: update_report.

full
generate_dcf_xlsx
Documents

Generate DCF Workbook (xlsx)

Render a forward DCF result into a professional Excel workbook (Summary + 5×5 Sensitivity heatmap + Inputs sheet).

full
generate_research_brief_docx
Documents

Generate 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.

full
generate_comps_xlsx
Documents

Generate Peer Comparables Workbook (xlsx)

Render a peer comparables table into an Excel workbook.

full

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_brief
Financial Analyst

Equity 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_shortlist
Portfolio Manager

Screen 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.

Args:sector?index?objective?as_of_date?top_n?
margin_and_moat_teardown
Financial Analyst

Margin & 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_memo
Financial Analyst

Peer 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_audit
Portfolio Manager

Quality & 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_review
Portfolio Manager

Capital 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?

survivorship_free_backtest
Quant Researcher

Survivorship-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.

Args:start_dateend_date
pit_factor_constructor
Quant Researcher

Point-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.

ratio_deep_dive
Ratio Specialist

Ratio 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.

Args:ticker
sector_ratio_screen
Ratio Specialist

Sector 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.

Args:sectorscreen_type
smart_money_brief
Smart Money (Institutional)

Smart 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_surveillance
Smart Money (Institutional)

Activist 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.

forensic_earnings_brief
Financial Analyst

Forensic 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_pulse
Portfolio Manager

Smart-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.

morning_briefing
Portfolio Manager

Morning 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).

earnings_pulse
Financial Analyst

Earnings 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_radar
Financial Analyst

Restatement 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.

activist_radar
Smart Money (Institutional)

Activist 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.

Args:watchlist_namelookback_days
screen_to_thesis
Quant Researcher

Screen → 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.

Args:criteria_namemax_results
portfolio_health_check
Portfolio Manager

Portfolio 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_flow
Financial Analyst

Sector 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.

dcf_build_flow
Financial Analyst

DCF 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.

Plan Access Matrix

Tools are gated by plan tier. Higher plans unlock all lower-tier tools.

ToolCategory
sample
sp500
full
PIT-safe
search_companiesDiscovery
get_company_fundamentalsFinancials
get_valuation_metricsValuation
get_financial_ratiosFinancials
get_sec_filing_linksDiscovery
get_capital_allocation_profileFinancials
get_peer_comparablesAnalysis
get_pit_universeUniverse
get_compute_ready_streamBulk Access
describe_schemaDiscovery
verify_fact_lineageAnalysis
compare_periodsAnalysis
screen_universeScreening
get_earnings_signalsSignals
search_filing_textDiscovery
get_insider_transactionsSmart Money
get_institutional_holdingsSmart Money
get_manager_portfolioSmart Money
get_blockholdersSmart Money
get_insider_sentimentSmart Money
get_top_holdersSmart Money
get_smart_money_flowSmart Money
save_thesisState
list_thesesState
get_thesisState
delete_thesisState
score_thesis_outcomeState
save_watchlistState
list_watchlistsState
get_watchlistState
delete_watchlistState
watchlist_diffDiscovery
create_alertState
list_alertsState
delete_alertState
test_alertState
list_alert_inboxState
mark_inbox_readDiscovery
dismiss_inbox_itemDiscovery
create_reportReports
get_reportReports
list_my_reportsReports
delete_reportReports
compute_dcfValuation
forensic_auditValuation
update_reportReports
generate_dcf_xlsxDocuments
generate_research_brief_docxDocuments
generate_comps_xlsxDocuments

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 with sec.gov/cgi-bin/browse-edgar for 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 with verify_fact_lineage for 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

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.