Vlada Docs

Start

Tools

Served tables

781

Companies

3,837

Instruments

149,487

Refusal codes

Doors

2MCP, REST

Three steps

1
Get a key
Free account at /data-access. The MCP connector signs in by OAuth; REST uses the key, shown once.

Connect an agent

Claude Code below; Claude, ChatGPT, Cursor, VS Code on Connect. Endpoint https://mcp.vladahealth.com/mcp.

claude mcp add --transport http --scope user vlada https://mcp.vladahealth.com/mcp

# first question
Use Vlada. Which ten Minnesota counties have the most Medicare Advantage members who must pick a new plan for 2027? Give me a table with the members in the market, the members who lose their plan and the share, then the source file, the data vintage and the response hash.

Or call REST

Every tool is POST https://api.vladahealth.com/v1/tools/<name>; body = the tool's inputs.

curl -X POST https://api.vladahealth.com/v1/tools/get_stars \
  -H "Authorization: Bearer $VLADA_API_KEY" -H "Content-Type: application/json" \
  -d '{"contract_id":"H5521","year":2026}'

The envelope

Field	Type	Holds
`status`	enum	complete · partial · refused · failed · queued
`value`	object	rows or the figure, with its unit
`source`	object	dataset, publisher, vintage of the public file
`caveats`	string[]	what to know before citing
`invariants_applied`	string[]	the rules the answer honoured
`response_hash`	string	replayable
`refusal`	object	code (one of 15), message, recover_with (the call that answers)

The loop

find_data_sources(query="medicare advantage enrollment by county")   # which table
describe_data_source(source_fqn="<fqn>")                               # grain, traps, required filters
get_enrollment(contract_id="H5521")                                     # a typed tool, or:
query_substrate(sql="SELECT ... FROM <fqn> WHERE state_code='OH' LIMIT 100")   # your own read-only SQL

Rule	Why
Independent calls in parallel	each call pays a fixed 1.5 to 5 s engine cost
Heavy price tools one at a time	one per server; on busy, wait 25 s and retry
Pin a state on hospital tables, a year on annual tables	scan budget; the refusal names the filter
Aggregate in SQL, never pull rows to count	rows per call and per month are capped by plan
Identical call within 15 min	served from cache

Held back on purpose

Rule	What you get instead
One payment basis per median	fee schedule, per diem and percent of charges are segmented, never blended
No figure below the declared floor	the tail is set aside as implausible_tail, with its count
Medicare and commercial never in one number	two numbers, each labelled
Insurer-file (TiC) lookups: coming soon	refused NO_COVERAGE; rates by insurer and plan come from hospital files
CMS suppression (* = 10 or fewer)	bounds, never a zero
An empty result	reported as an absence with what was searched

Everything served

Section	Count	What
Data	781	tables with columns, grain, traps, required filters
Companies	3,837	one permanent ID each; owners, holdings, over time
Tools	58	each with a real answer
Recipes	110	question → tool → arguments
Errors	15	codes, meaning, way out, HTTP status

This page as markdown: /docs-md/recipes.md · every page in one file: /llms-full.txt