Valuein MCP server

Valuein — SEC EDGAR fundamentals for analysts, quants, and AI agents

Point-in-time, survivorship-free SEC fundamentals — built for AI agents, safe enough for institutions that fear AI. Every number is born in a filing and carries a fact_id; the model never mints a digit. Streamed as Parquet, queried with DuckDB or natural language, reproducible run to run.

This repository is the public home and discovery hub for the Valuein data platform. It hosts the documentation, examples, notebooks, and the MCP registry manifest used by AI agents to find us. Source code for the SDK, MCP server, and data pipeline lives in dedicated repositories — this is the front door.

pip install "valuein-sdk>=1.0.0" # data for code
# or add this URL to any MCP-capable AI client:
# https://mcp.valuein.biz/mcp     # data for agents

---

What's in here

You want to…	Go to
Try the SDK in 30 seconds without a token	Quickstart
See every channel we ship through	Distribution channels
Check pricing and what each plan unlocks	Plans & access
See why AI agents are first-class citizens here	Built for AI agents
Connect an AI agent (Claude, Copilot, ChatGPT, Cursor…)	MCP for AI agents
Set up the Workspace by role (analyst, PM, quant, creator)	docs/WORKSPACE_GUIDE.md
Read the data model	Data model
Find a quick recipe by role	Recipes by role
Run end-to-end Python examples	examples/python/
Run interactive notebooks (Colab)	examples/notebooks/
Read the methodology / SLA / compliance	Documentation
Report a data error or request a feature	Support & community
Contribute an example or notebook	CONTRIBUTING.md

---

The data product

Survivorship-bias-free, point-in-time US fundamentals sourced directly from SEC EDGAR.

• Every SEC-reporting US public company since 1993 — 10-K, 10-Q, 8-K, 20-F, 40-F, and amendments, for active and delisted companies alike: every bankruptcy, merger, and delisting stays in
• Raw XBRL tags normalized to canonical standard_concept names plus materialized financial ratios (FY + TTM); unmapped tags are exposed under 'Other' rather than dropped
• Parquet tables — fundamentals, ratios, index membership, restatement events, plus the smart-money and Form ADV adviser tables on the Institutional tier
• Cloud Parquet on Cloudflare R2 — stream with DuckDB; no database setup, no local downloads
• PIT-correct — every fact carries filing_date and millisecond-precision accepted_at

Counts move with every snapshot, so this page does not copy them; read them live. client.manifest() returns the snapshot id, last_updated and your plan's tables; curl -s https://data.valuein.biz/v1/sample/manifest.json | jq .schema_version prints the live schema version; https://data.valuein.biz/v1/plans gives each plan's universe size and history window; docs/data_catalog.md lists the canonical concepts and ratios.

Why it's different

Property	What it means for you
🕒 Point-in-time	filing_date <= trade_date removes look-ahead bias. accepted_at gives intraday resolution for same-day signals.
⚖️ Survivorship-bias free	Delisted, bankrupt, and acquired companies remain in every snapshot — your backtest sees the universe the market saw.
📊 Standardized concepts	Both the raw XBRL tag (fact.concept) and the canonical name (fact.standard_concept) are on every row. No hidden mapping table.
🔍 CPA-verified catalog	Every standard_concept carries a review_confidence — 1.0 once an accountant has signed off on its name, statement and rule (then it's locked; the pipeline only ever adds new concepts, never mutates a verified one), 0.7 while provisional. Filter review_confidence >= 1.0 for the labels analysts, quants and AI models can agree on and train against.
🚀 DuckDB-native	Millisecond analytics over remote Parquet via httpfs. Zero database provisioning.
🔁 Append-only restatements	A 10-K/A adds a new row — the original stays. Reconstruct the as-reported view of any historical date.
🧾 Measured, published accuracy	Mathematical consistency checked against published, cited accounting identities — CI-gated, and re-derivable yourself with one DuckDB command. The current measured figure lives in docs/accuracy/baseline.json.
🔐 One token, every channel	The same Bearer token authenticates the SDK, MCP server, and bulk-data API.

---

Built for AI agents

Valuein is MCP-first and agent-agnostic: the same typed tool surface works in Claude, Copilot, ChatGPT, Perplexity, Gemini, Grok, Cursor, or your own LangGraph / CrewAI agent. The design goal is simple — the model never mints a number. Numbers are born in tools, carried as provenance-tagged facts, and the model is only allowed to arrange words around figures it was handed.

Guarantee	How it's enforced
Fact-level lineage	Every figure a tool returns carries a fact_id and its source filing; verify_fact_lineage round-trips any fact_id back to the exact SEC filing URL in one call.
Zero look-ahead	Every time-series tool accepts as_of_date and reconstructs the information set as of that date — the same PIT discipline the Parquet layer enforces for backtests.
Reproducible runs	Deterministic, idempotent tools: same inputs, same output. No rolling windows, no hidden "latest". Agents can cache, retry, and replay; you can reproduce a run later.
Agent-agnostic state	Theses, claims, watchlists, signals, and reports persist server-side across sessions and across clients — save a thesis from Claude today, list it from Cursor tomorrow.
Human-on-the-loop (HOTL)	Mutating and outward-facing tool actions go through a staged-action approval ledger: the agent proposes, a human approves, and the decision lands in an immutable audit entry. Read-only tools never stage.
Governed managed runs	Server-side managed agent runs execute at temperature 0 with a model allow-list and destructive-tool stripping — reproducible research, not improvisation.
Graded track records	Saved theses and claims are scored against subsequent fundamentals; publishing builds a public, verifiable track record — your agent keeps score.

The full tool reference is in docs/MCP_TOOLS.md; agent-facing runtime instructions are in AGENTS.md.

---

Distribution channels

The same dataset, delivered four ways so it lands where you already work.

Channel	Audience	Endpoint / install
Python SDK	Quants, engineers, data scientists	pip install valuein-sdk · PyPI
MCP server	AI agents (Claude, Copilot, ChatGPT, Cursor, custom)	https://mcp.valuein.biz/mcp · server.json
Web dashboard	Retail, executives, non-technical users	valuein.biz
Bulk data API	B2B partners, fintech platforms	https://data.valuein.biz · contact us

A single Stripe-issued token unlocks every channel at your tier — no per-channel billing.

---

Plans & access

Pricing and feature scope are mirrored from valuein.biz/pricing — the website is the source of truth and our checkout flow routes to the correct Stripe product.

Plan	Universe	History	Get it
Sample	Every S&P 500 member since 1996, former members included	5 calendar years + YTD	Free, no signup: pip install "valuein-sdk>=1.0.0"
Benchmark	Every S&P 500 member since 1996, former members included	Full history	Free, register
Pro	Full active + delisted universe incl. foreign issuers (20-F, 40-F), fundamentals dataset	Rolling 15 years (from 2011 today)	Subscribe
Institutional	Same universe + smart-money dataset (insider transactions on Forms 3/4/5/144 + institutional ownership on Forms 13F/13D/13G)	Full history back to 1993	Subscribe
Enterprise	Organisations and teams, by Enterprise Agreement: the whole dataset, multi-seat · display in your own products and client deliverables, with attribution, where the Order Form says so · dedicated infrastructure · negotiated scope	Custom	sales@valuein.biz

Redistribution, resale and white-label are not part of any plan, Enterprise included: data vendors and platforms sign a separate Redistribution Licence (sales@valuein.biz).

Prices, universe sizes, history windows and rate limits are served live; read them instead of a copy:

curl -s https://data.valuein.biz/v1/plans \
  | jq '.plans[] | {displayName, priceUsd, universeSize, earliestYear, perMinute, perHour}'

Each tier removes a different buyer objection — Pro removes the universe + history limits on the fundamentals dataset; Institutional adds the smart-money dataset (insider transactions + institutional ownership), unlimited history back to 1993, filing-event webhooks, and a single-seat internal-use licence (no redistribution); Enterprise is for organisations and teams: an Enterprise Agreement for multi-seat use and, where the Order Form says so, display in your own products and client deliverables with attribution, plus dedicated infrastructure, service levels and bespoke contracts. Redistribution, resale and white-label need a separate Redistribution Licence, which no plan includes.

How you pay: three parts, no run limits

Subscribe for the data. Pay only for the AI you use.

1. Subscription = data. Your plan sets how much of the market you can see (companies, years of history, filing types, datasets), plus API rate limits, daily bulk downloads, webhooks, licence and support. Plans: Sample, Benchmark, Pro, Institutional, Enterprise.
2. Balance = AI work. One balance pays for Valuein AI chat, agent runs and coverage reads. There are no run limits and no Workspace run fee: a run costs only the AI compute it uses. Every plan includes a monthly compute allowance, and new accounts start with a welcome credit. Using your own Anthropic or OpenAI key costs nothing on our side.
3. Agent payments = AI agents without an account. An agent buys a 24-hour company pass or pays a per-run fee, by card, over MPP (below). A subscriber pays the same prices for data outside their plan.

Agent payments (MPP)

Autonomous AI agents that need data outside their plan can pay by card over the Machine Payments Protocol — no human checkout loop, no account, no minimum. MPP is the only agent payment method, and it is offered on the full MCP endpoint (https://mcp.valuein.biz/mcp) only. The agent calls POST https://api.valuein.biz/api/mpp/call, receives a 402 quoting the exact price, pays, and retries the same URL; the data comes back inline. Funds are held first and captured only after the data is delivered, so you are never charged for data you did not receive.

Payment is card-only today. Fetch https://api.valuein.biz/api/mpp/well-known to see which networks are live before paying.

What you buy	Price
Company pass, pro level: one company, every company-data tool, Pro history (from 2011), 24 hours	$1.00
Company pass, full level: the same with history back to 1993, plus the smart-money tools, 24 hours	$5.00
Compute run (compute_dcf, forensic_audit, document generation, …), plus a pass for each company it reads	$1.00 per run
Verification run (figure-checking tools, up to 50 figures), plus a pass for each company outside your plan	$1.00 per run
Universe run (screen_universe, get_pit_universe, run_backtest)	$5.00 per run

The payment returns your pass in the X-Valuein-Mpp-Pass header; send it as x-valuein-mpp-pass on later /mcp calls to reuse it for that company until it expires. Any Valuein token, the free Benchmark one included, pays 50% less (present it in X-Valuein-Authorization), and every account verifies its first 100 figures free, once. Search and provenance tools are free; Workspace tools (watchlists, signals, agents, reports) and bulk streaming are not sold per call. Live prices: curl -s https://api.valuein.biz/api/mpp/tools; a 402 quotes the exact amount before anything is authorized. If you pay repeatedly, a Pro or Institutional subscription is cheaper. See AGENTS.md for the full flow.

The whole pattern — an agent that buys its own data, safely — is written up as a reference implementation in docs/AGENT_ECONOMY_RAIL.md: the MPP hold-verify-capture flow, company passes, why it's the safe default, and a runnable demo — examples/python/agent_buys_its_own_data.py — that discovers the rail and reads back a live quote for free.

Rate limits per tier are the perMinute / perHour fields of https://data.valuein.biz/v1/plans (the jq command under Plans & access prints them).

---

Quickstart (30 seconds, no token)

Pick whichever Python workflow you already use — both work in any virtual environment, and both run the same code below:

# Option A — pip (universal, ships with Python)
python -m venv .venv && source .venv/bin/activate
pip install "valuein-sdk>=1.0.0"

# Option B — uv (10–100× faster; install from https://docs.astral.sh/uv/)
uv venv && source .venv/bin/activate
uv pip install "valuein-sdk>=1.0.0"

Zero-friction by design. No VALUEIN_API_KEY? No problem. The SDK detects the missing token and falls back to the SAMPLE dataset (S&P 500, last 5 years); the edge gateway does the same — GET /v1/{sp500,pro,full}/:table with no Authorization header automatically 302-redirects to /v1/sample/:table. The snippet below runs as-is.

from valuein_sdk import ValueinClient

with ValueinClient() as client:
    print(client.me())               # {plan, status, email, createdAt}
    print(client.manifest())         # snapshot id, last_updated, tables
    print(client.tables())           # tables your plan can read (they load on first use)

    df = client.run_query("""
        SELECT r.symbol, r.name, r.sector
        FROM   "references" r
        JOIN   index_membership im ON im.cik = r.cik
        WHERE  im.index_name = 'SP500'
          AND  im.removal_date IS NULL
          AND  r.is_active = TRUE
        ORDER  BY r.name
        LIMIT  10
    """)
    print(df)

That's a real query against the live S&P 500 sample. Add a token only when you need full universe or full history:

# optional — the sample tier works without a key
export VALUEIN_API_KEY="your_token_here"      # or add this line to a .env file

The same code now reads from your tier — no other changes. ValueinClient() reads VALUEIN_API_KEY from the environment, or from the first .env it finds walking up from the working directory; ValueinClient(api_key="") forces the free sample whatever the environment holds. The curl and DuckDB examples in this repo keep the same token in $VALUEIN_TOKEN: it is the same token under a shell-variable name, and the SDK does not read that one.

Production pattern — context manager, typed errors, pre-built templates

from valuein_sdk import (
    ValueinClient,
    ValueinAuthError,
    ValueinPlanError,
    ValueinRateLimitError,
    ValueinAPIError,
    ValueinError,
)

# Two-level try/except is intentional:
#   outer = init errors raised by ValueinClient.__enter__ (auth, manifest, 503)
#   inner = per-query errors raised by run_query / run_template (rate-limit,
#           plan denial, bad SQL). Each level dispatches by exception type so
#           you can act on the right cause — exit on auth, sleep on rate-limit,
#           upsell on plan, log + skip on a single bad row.

try:
    with ValueinClient() as client:
        try:
            # 1) Build & run a raw SQL query → pandas DataFrame
            sql = "SELECT COUNT(cik) FROM entity"
            result = client.run_query(sql)
            print(result)

            # 2) Run a named SQL template with kwargs (the SDK quotes safely)
            df = client.run_template(
                "fundamentals_by_ticker",
                ticker="AAPL",
                start_date="2020-01-01",
                end_date="2024-12-31",
                form_types=["10-K", "10-Q"],
                metrics=["TotalRevenue", "NetIncome", "OperatingCashFlow"],
            )
            print(df.head())
        except ValueinPlanError:
            print("This query needs a higher plan — see valuein.biz/pricing.")
        except ValueinRateLimitError as e:
            print(f"Rate limited; retry in {e.retry_after}s.")
        except ValueinError as ve:
            # Catch-all for any other per-query failure (validation, bad SQL, etc.)
            print(f"Query failed: {ve}")
except ValueinAuthError:
    raise SystemExit("Token missing or expired — set VALUEIN_API_KEY.")
except ValueinAPIError as e:
    print(f"Gateway error during init (HTTP {e.status_code}).")
except Exception as e:
    print(f"Initialization failed: {e}")

The SDK ships named SQL templates for the most common screens, ratios, and PIT backtests. List the ones your installed version carries:

from valuein_sdk import ValueinClient
with ValueinClient() as c:
    print(c.list_templates())

Statements and screens, every number traced to its filing

from valuein_sdk import ValueinClient

with ValueinClient() as client:  # no token: free sample tier
    fin = client.financials("AAPL")  # income, balance sheet, cash flow as known at as_of
    print(fin.income)
    print(fin.lineage.head())  # each number's fact_id, filing accession and acceptance time

    screen = client.screen("2024-06-28", universe="SP500").where("return_on_equity > 0.15")
    print(screen.top(10, by="gpoa").to_pandas().summary())  # members on that date, delisted included

The main verbs

You want…	Call	Plan
Raw SQL over point-in-time views	client.run_query(sql), client.duckdb()	all
Statements as known on a date	client.financials("AAPL", freq="FY") ("Q", "TTM"; .as_filed())	all
Index members on a past date (delisted included)	client.universe(dates=[...]), client.pit_universe("2022-06-30")	all
Ratios known on those dates	client.signal_panel(members, ratios=[...])	all
A point-in-time screen	client.screen("2024-06-28").where("return_on_equity > 0.15")	all
A two-stage DCF with traced inputs	client.dcf("MSFT", stage1_growth_rate=0.08)	all
Peers and restatements	client.peers("MSFT", n=5), client.restatements(ticker="MPWR")	all
Mirror or pin the data	client.sync(path), ValueinClient.from_bundle(path)	plan-limited

from valuein_sdk import ValueinClient

client = ValueinClient()  # reads VALUEIN_API_KEY; no key = free sample

# S&P 500 members on a past date, later-removed companies included
members = client.universe(dates=["2022-06-30"])

# Return on equity as it was known on that date
panel = client.signal_panel(members, ratios=["return_on_equity"])
print(panel.head())

# A DCF with your growth assumption; every input traced to its filing
dcf = client.dcf("MSFT", stage1_growth_rate=0.08)
print(dcf.value_per_share, dcf.enterprise_value)

# Numbers a later filing changed, with both filings
print(client.restatements(ticker="MPWR").head())

The same client builds point-in-time factor panels from as-filed, point-in-time or restated numbers, traces every cell to its filing, and mirrors or pins a data snapshot: docs/SDK_USE_CASES.md.

Bring your own prices: join the closes you hold to point-in-time SEC EDGAR filings data, from the SDK or MCP, on any plan: docs/BRING_YOUR_OWN_PRICES.md.

Reference: docs/QUERY_COOKBOOK.md (DuckDB recipes) · docs/data_catalog.md (canonical concepts) · PyPI README (SDK quickstart).

---

Recipes by role

Every link below points to a runnable script in examples/python/; most pair with a notebook in examples/notebooks/. The Sample tier runs every example except the Institutional smart-money screen — no token, no signup.

You are a…	Start with	What you'll see
Financial analyst	financial_analysis.py	Revenue trend, margin walk, peer comparison from one ticker
Quant / researcher	pit_factor_dataset.py	Point-in-time, survivorship-free factor file, ready for your own backtester
Portfolio manager	entity_screening.py	Screen the S&P 500 as it stood on a past date, including later-removed members
Forensic analyst	restatement_radar.py	Every restated number, how it was disclosed, both filings to verify
Valuation modeler	dcf_inputs.py	client.dcf(): a two-stage DCF with your assumptions, every input traced to its filing
Auditor / compliance	filing_provenance.py	Click-through SEC EDGAR links per filing — open the iXBRL viewer on the exact source document behind a number
Data engineer	production_service.py	Scheduled point-in-time extract to Parquet: limits, logging, exit codes
First-time user	getting_started.py	Plan check, ticker → CIK, first fundamentals query
Building an AI agent	MCP for AI agents	Use natural language — no SDK required

Run any of them:

# Sample tier — works without a token
python examples/python/getting_started.py

# Paid tier
VALUEIN_API_KEY=xxx python examples/python/pit_factor_dataset.py

---