# Beanvest agent guide

Use the same sourced financial data that appears on Beanvest. Choose REST for integrations, Markdown for reading, or remote MCP for tool-capable clients. No API key is required. Client logos identify setup options; they are not evidence of a certified integration.

## REST quick start
```sh
curl -X POST 'https://beanvest.com/api/v2/search' -H 'Content-Type: application/json' --data '{"query":"Tesla","limit":10}'
curl 'https://beanvest.com/api/v2/pages/tsla/valuation?metric=pfcf&range=5Y&limit=20'
curl 'https://beanvest.com/stock/tsla/revenue.md?frequency=yearly'
```

Search results include canonical symbols, aliases, available page paths, reporting currency and dated USD market-cap metadata. All 518 supported issuers can be discovered with limit/offset pagination. GET /api/v2/companies retains the complete financial-summary index. GET /api/v2/financials/{symbol} returns the validated raw dataset and full filing facts; it is larger than a page response. GET /api/v2/metrics documents all 46 calculated metrics.

## Financial pages
GET /api/v2/pages/{symbol}/{topic}. Moat and Fair Value are versioned research pages; chart frequency/range/metric filters do not apply. Fair Value retains existing Premium access, with public example companies. Topics: overview, moat, fair-value, revenue, valuation, cash-flow, margins, returns, capital, deliveries, optimus. Deliveries and Optimus are Tesla-only. Unknown companies/topics return 404. Aliases resolve to the canonical symbol in the response.

Options:
- frequency=quarterly|yearly|daily. Daily is valuation-only and defaults there; otherwise the available reported frequency is selected. If daily history is unavailable, the response identifies the fiscal-period fallback.
- range=1Y|3Y|5Y|10Y|ALL. Valuation defaults to 5Y, matching the interactive charts. Other topics retain all reported history.
- from and to: inclusive YYYY-MM-DD boundaries on period-end/completed-close date; use range=ALL if a valuation date interval reaches beyond five years.
- metric: one ID from the page definitions to reduce response size.
- deductSbc=true|false (default false). wacc=0..100, as a percentage scenario; the default is the company industry proxy.
- limit=1..1000 (default 200), offset=0..100000. Rows are newest-first. Follow pagination.nextOffset; null means complete. Search uses a maximum limit of 50.

Responses identify schemaVersion, company, path, topic, options actually used, definitions with explicit units, dated rows, null-value issues, coverage, pagination, sources, market-price provenance, pendingFiling, freshness and rawDataPath. The raw dataset provides selected filing facts, accession/tag/date/units and hashes. Tesla rows retain report page/table/row/column evidence. Optimus returns disclosure status and sources, not fabricated operating series.

Cash-flow pages include sbc_fcf and sbc_ocf scalar percentages. Their denominators use the same fiscal period, before any SBC scenario; nonpositive denominators remain null. capitalAllocation contains category amounts, percentages, tracked-use totals, missing/excluded categories, scopes and raw observation references. It shares the page's date filter and pagination. It is not a complete cash-flow reconciliation or a percentage of OCF.

Every financial page supports .md and .json. For example /stock/meta/cash-flow.md?frequency=yearly and /stock/meta/cash-flow.json. Expanded charts have dedicated subpaths, such as /stock/meta/valuation/charts/pe.json?range=ALL or /stock/tsla/charts/revenue.md. The chart URL fixes its series; stacked revenue retains its segments, and capital-allocation retains percentages and tracked amounts. The home counterpart is the public catalog, not personal favorites. /developers.md is this guide; /developers.json is OpenAPI; /developers/mcp.md and .json describe the MCP. HTML pages advertise alternate formats with link rel=alternate.

## MCP
Endpoint: https://beanvest.com/api/mcp. Stateless Streamable HTTP; JSON responses, no server-initiated SSE stream. POST accepts one JSON-RPC 2.0 message and requires Accept: application/json, text/event-stream and Content-Type: application/json. GET and DELETE return 405. Accepted notifications return 202 with no body. Protocol versions: 2025-11-25, 2025-06-18, 2025-03-26. No OAuth/key is needed for public data. Cross-origin browser requests are limited to the service origin, Claude and ChatGPT; server clients may omit Origin.

Tools:
- search_companies: Find supported companies by name, ticker or share-class alias. Returns canonical symbols, available pages, reporting currency and dated USD market caps; no private favorites.
- get_company_page: Read the same sourced values and formulas as a financial page: revenue, valuation, cash flow, margins, returns, capital, Tesla deliveries, Optimus disclosures, Moat or Fair Value. Research pages expose versioned analysis and do not accept chart filters. Fair Value retains Premium access except free example companies. Null is unavailable. Pagination is newest-first; statistics cover the full selected range. Read rawDataPath for complete filing evidence.
- get_metric_definitions: Inspect the financial metric catalog and calculation conventions before comparing companies. Units money/shares denote reporting-currency millions/million shares.

Claude Code:
```sh
claude mcp add --transport http beanvest https://beanvest.com/api/mcp
```
Codex:
```sh
codex mcp add beanvest --url https://beanvest.com/api/mcp
```
For a remote-HTTP-capable client such as Claude or ChatGPT, add the endpoint in its custom connector/app configuration. Availability and setup controls depend on the client. For Cursor, add this to its MCP configuration:
```json
{
  "mcpServers": {
    "beanvest": {
      "url": "https://beanvest.com/api/mcp"
    }
  }
}
```
These are setup templates. Verify initialize, tools/list and one get_company_page call before claiming a connected client. Do not configure this as legacy HTTP+SSE or local stdio. REST/Markdown work without MCP.

## Skills and prompt
Read/download https://beanvest.com/skills/beanvest-research/SKILL.md. Put SKILL.md in a named beanvest-research folder inside the skill directory supported by your agent. Review it and preserve an existing skill; there is no universal installation command. Copy-ready prompt: https://beanvest.com/agent-prompt.txt.

## Data conventions
- Null means an unavailable input or undefined calculation, never zero. Values are unrounded; money and shares are in millions unless a column states otherwise.
- Fiscal periods use actual reporting start/end dates. Annual reported values are not constructed by adding quarterly EPS or weighted share counts. Partial years are labelled.
- FCF uses operating cash flow minus reported cash capital investment, preferring PPE purchases. The productive-assets fallback can also include software and intangibles. Acquisitions and noncash leases are excluded. Deduct SBC is an optional economic-cost scenario; missing SBC remains unavailable.
- SBC / FCF and SBC / OCF compare amounts from the same fiscal period. SBC / FCF always uses FCF before SBC deduction; nonpositive denominators are undefined and values above 100% remain valid.
- Capital allocation percentages describe available tracked cash uses, not all company spending or a fraction of OCF. Missing categories remain null, negative payments are excluded and SBC is noncash. Annual shares use reported annual amounts.
- Valuation uses completed, split-adjusted closes without dividend adjustment and a complete trailing year. Financial bases become eligible after publication; selected facts can contain later restatements. This is not a vintage-filings backtest.
- Mean and median use all valid observations in the selected date range before pagination. Historical pricing labels compare the latest positive value with its own median and do not estimate intrinsic fair value.
- Reporting currencies are retained without conversion. USD market capitalization, where available, is a separate dated Nasdaq snapshot.
- WACC is an editable US industry scenario across history, not a historical company cost of capital. Industry exclusions, missing inputs and pending filings remain explicit.

## Errors and verification
400: invalid dates, options, pagination or JSON. 404: unsupported company/topic. 413: MCP body exceeds 16 KiB. 503: validated snapshot unavailable. MCP invalid tool arguments return isError=true; unsupported protocol/method/origin errors follow the transport/JSON-RPC contract. Reads have no account or financial side effects. Apply timeouts and bounded backoff for transient errors. Do not send private portfolio data or account credentials.

Test actual HTTP/MCP calls separately from claimed client installations. Confirm as-of dates, null handling, reporting currency, pagination and evidence. Data refreshes use the existing validated pipeline; retrieval dates do not mean a new filing was published that day.