Ground an agent
Connect the MCP server, give the agent a system prompt that keeps it on the data, and cite meta in every answer, so it answers from current, versioned sources instead of memory.
| Plan | Every plan. Each tool needs the plan its endpoint does: payer metrics on Builder, joined answers and coverage on Pro |
| Tools | Every MCP tool, read-only, at most 10 results each, each citing source and data_version |
| Cost | An MCP tool call costs exactly what the REST call does |
An agent working from memory will state last year's code, miss a shortage that started last week and can't know whether a provider was excluded last month. Give it the tools, tell it to use them for every fact, and make it cite the release it used.
1. Connect the MCP server
Remote, nothing to install (Claude Code shown; other clients):
claude mcp add --transport http healthcare-dev https://mcp.healthcare.dev/mcp \
--header "Authorization: Bearer $HDEV_API_KEY"Any client that takes a JSON config:
{
"mcpServers": {
"healthcare-dev": {
"url": "https://mcp.healthcare.dev/mcp",
"headers": { "Authorization": "Bearer hdev_live_..." }
}
}
}Or run it locally over stdio: npx -y @healthcare.dev/mcp with HDEV_API_KEY set. Don't commit
a config file that contains your key; for a shared or production agent, give it a
child key with its own scopes and spend cap.
2. Give it a system prompt
You answer questions about US healthcare reference data: codes, drugs, providers, Medicare
coverage and payer prior authorization.
- Use the healthcare-dev tools for every code, drug, provider, coverage or payer fact. Never
answer those from memory, even when you think you know.
- Cite every fact: the tool's `source` and `data_version`, and the `evidence` link when there is
one.
- When an answer has `derivation`, say how it was reached: `source_stated` (the source says it),
`derived` (concluded from what the source says) or `reviewed` (a person checked it). Give
`confidence` and suggest reading the evidence when it is below 1.
- `not_listed`, an empty list or `false` from a check means the source lists nothing, not that
the answer is no. Say so, with the tool's note.
- Show the disclaimer the tool returns. This is reference data, not medical, coding, billing,
coverage or prior authorization advice.
- Never send or ask for patient information: no names, dates of birth, member ids or notes
about a person.
- If a tool answers `plan-upgrade-required`, say which plan it needs; don't guess the answer.Coding agents can load the same rules as a skill: Agent skill.
3. Cite meta when you call the API yourself
When your own code calls the API and passes results to a model, pass the provenance with the
data. Every response's meta has source, data_version, retrieved_at and license;
meta.license_terms says what you may show end users.
TypeScript
import { HealthcareDev } from "@healthcare.dev/sdk";
const hdev = new HealthcareDev();
const { data, meta } = await hdev.providers.exclusions("1003926940");
const citation = `${meta.source} ${meta.data_version}, retrieved ${meta.retrieved_at} (${meta.license})`;
const context = JSON.stringify({ answer: data, note: data.note, citation });
// pass `context` to your model as a tool result, with the system prompt abovePython
import json
from healthcare_dev import HealthcareDev
hdev = HealthcareDev()
r = hdev.providers.exclusions("1003926940")
meta = r["meta"]
citation = f"{meta['source']} {meta['data_version']}, retrieved {meta['retrieved_at']} ({meta['license']})"
context = json.dumps({"answer": r["data"], "note": r["data"]["note"], "citation": citation})Ask an agent
Each needs live data, so an agent without the tools can't answer it correctly:
- "Is NPI 1003926940 excluded by the OIG or opted out of Medicare? Cite the source." (Free)
- "Is NDC 0003-0894-21 in shortage or under an open recall?" (Free)
- "What changed in the latest HCPCS release?" (Builder)
- "Does Medicare support code 11720 for diagnosis B35.1 in Texas?" (Pro)
What it is not
The tools give an agent reference data with its provenance. They don't make the agent's conclusions clinical, coding, billing or coverage advice; keep a person in the loop for those.