Valuein MCP Server

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

Survivorship-bias-free, point-in-time US fundamentals — streamed as Parquet, queried with DuckDB or natural language.

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          # 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

---

The data product

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

• 12M+ filings — 10-K, 10-Q, 8-K, 20-F, 40-F, and amendments since 1993
• 105M+ standardized facts across 19,000+ active and delisted US public-company entities
• 11,966 raw XBRL tags normalized to ~286 canonical standard_concept values (95%+ coverage)
• 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
• Semantic core — every 10-K / 10-Q / 20-F's narrative sections (Risk Factors, MD&A, Business, Legal, Controls) chunked and indexed for natural-language search via the MCP server

Why it's different

---

Distribution channels

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

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.

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 commercial redistribution license under a business-hours SLA; Enterprise adds dedicated infrastructure and bespoke contracts.

Pay-per-call (MPP)

Autonomous AI agents that hit a rate or tier limit can pay per request using Stripe card tokens — no human checkout loop. Payment uses the Machine Payment Protocol. The agent quotes a price, charges a card Shared Payment Token, then retries the MCP call with the confirmed token.

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

PAYG is priced at 5× the subscription-equivalent rate — steady-state agent usage is almost always cheaper with a Pro or Institutional subscription. Daily spend caps exist per token as abuse protection; caps are raisable on request. See AGENTS.md for the full three-step MPP flow.

Rate limits per tier (canonical at https://data.valuein.biz/v1/plans):

---

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

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

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())           # currently loaded tables

    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 — sample tier works without a key
echo 'VALUEIN_API_KEY="your_token_here"' >> .env

The same code now reads from your tier — no other changes.

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 54 named SQL templates for the most common screens, ratios, and PIT backtests. List them:

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

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/ (mirror notebook in examples/notebooks/). The Sample tier runs every example — no token, no signup.

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/factor_screen.py

---

Data model

Full schema in docs/schema.json (machine-readable) and docs/data_catalog.md (canonical concept names).

Date columns — which to use when

For any cross-company backtest, always filter by filing_date <= trade_date. Filtering by report_date introduces look-ahead bias.

Three patterns that pay off in DuckDB

1. Start from references (one join for cross-company filters; membership is in index_membership):

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          -- current member
  AND  r.is_active     = TRUE
  AND  r.sector ILIKE '%technology%'

2. LATERAL for the latest filing per company:

JOIN LATERAL (
    SELECT accession_id, filing_date FROM filing
    WHERE  entity_id = r.cik AND form_type = '10-K'
    ORDER  BY filing_date DESC LIMIT 1
) f ON TRUE

3. Pivot multiple concepts in one fact scan:

SELECT
    MAX(CASE WHEN standard_concept = 'TotalRevenue'       THEN numeric_value END) AS revenue,
    MAX(CASE WHEN standard_concept = 'StockholdersEquity' THEN numeric_value END) AS equity
FROM   fact
WHERE  standard_concept IN ('TotalRevenue', 'StockholdersEquity')
GROUP  BY accession_id

Quarterly cash flows: use COALESCE(derived_quarterly_value, numeric_value) — Q2/Q3 10-Qs report YTD; this column isolates the single quarter. CAPEX sign varies by filer — always ABS(capex).

The full cookbook — 20 recipes, 8 anti-patterns, end-to-end factor screen — lives in docs/QUERY_COOKBOOK.md.

Canonical concept names

Query fact.standard_concept with canonical names like 'TotalRevenue', 'NetIncome', 'OperatingCashFlow', 'CAPEX', 'StockholdersEquity' — not raw XBRL tags ('Revenues', 'NetIncomeLoss', 'Assets'). The full list lives in docs/data_catalog.md and the machine-readable form is in docs/data_catalog.json.

---

MCP for AI agents

Valuein ships a remote Model Context Protocol server so any MCP-capable agent (Claude Desktop, Cursor, Codex, custom) can answer fundamentals questions without writing code.

• Endpoint: https://mcp.valuein.biz/mcp (Streamable HTTP, MCP spec 2025-11-25)
• Auth: Authorization: Bearer <your_api_token> — same token as the SDK and bulk-data API
• Manifest: server.json — published to registry.modelcontextprotocol.io as io.github.valuein/mcp-sec-edgar
• Reference: docs/MCP_TOOLS.md — every tool, every parameter, every tier gate

Tools

The server exposes 67 live tools + 1 stub (68 total), plus 22 agentic SOP prompts (two flagship cross-persona briefs — equity_research_brief and screen_and_shortlist — plus specialised chains for analyst, PM, quant, ratio, smart-money, and workflow personas) and 3 data resources (schema://{table}, reference://sp500, pricing://current). Tier gating happens at the data layer — Sample / Free tokens see Sample / S&P 500 data; Pro sees the full 19,000+-entity universe with a 15-year point-in-time window (2011 → present); Institutional unlocks the smart-money tools (insider transactions on Forms 3 / 4 / 5 / 144 + institutional ownership on Forms 13F / 13D / 13G), unlimited history back to 1993, filing-event webhooks, and the commercial redistribution license.

Discovery & schema

Fundamentals & ratios

Filings & lineage

Comparison & analytics

Bulk & semantic

Smart money — Institutional tier and above

The smart-money bundle replaces Bloomberg's INSIDER<GO> / OWNER<GO> / HDS<GO> screens with a single Valuein token. Each tool reads a per-CIK Parquet partition and returns structured rows with the lineage envelope for one-click SEC verification.

Configure in Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "valuein": {
      "url": "https://mcp.valuein.biz/mcp",
      "headers": { "Authorization": "Bearer YOUR_VALUEIN_API_KEY" }
    }
  }
}

Same URL + Bearer token works for any MCP client that supports Streamable HTTP remotes — Cursor, Codex, your own LangGraph / CrewAI agent.

---

Examples in this repository

Every script and notebook works against the SDK published on PyPI. The Sample tier runs without a token; add VALUEIN_API_KEY to use a paid tier.

Python scripts (examples/python/)

Jupyter notebooks (examples/notebooks/)

---

Documentation

Everything in docs/ is kept in sync with the production data and the SDK on PyPI.

---

Support & community

GitHub Issues is the primary support channel. Use the right template — it routes correctly and gets faster triage.

For private or contractual matters (DPAs, procurement, DDQs, enterprise SLAs): support@valuein.biz.

Contributions — examples, notebook improvements, documentation fixes, query recipes — are very welcome. See CONTRIBUTING.md for the workflow and CODE_OF_CONDUCT.md for community standards.

---

License & disclosure

Apache 2.0. See NOTICE for attribution.

This repository is provided for research and educational purposes. It is not investment advice. No warranty of fitness for any particular trading, investment, or regulatory purpose is implied.