Skip to main content
These docs are published in forms that AI coding assistants and agents can read directly. Every page also has a Copy page menu to copy it as Markdown or open it in ChatGPT or Claude.
The docs MCP server searches these docs. It does not call the HealOS API and never sees your data.

​
Use HealOS from an AI agent (MCP)

healos mcp runs an MCP server on your computer, so Claude Desktop, Claude Code, Cursor and other MCP clients can read your HealOS data through the HealOS API. It is part of the HealOS CLI and uses the key you signed in with, with that key’s scopes, rate limits and audit log.
healos mcp ships in the next release of @healos/cli on npm. The configs below work once that release is out; check with npx @healos/cli@latest mcp --help.

​
Set it up

  1. Sign in once, so the key is stored in your Keychain (or a file only you can read) instead of in the agent’s config:
    The key is read-only unless you ask for more scopes. See Sign in.
  2. Add the server to your client: in Claude Desktop, Settings → Developer → Edit Config (claude_desktop_config.json); in Cursor, ~/.cursor/mcp.json (or .cursor/mcp.json in a project).
Add "--profile", "<name>" to args to use another saved profile. Pin a version you have tested (@healos/cli@<version>) if you don’t want updates picked up automatically.

​
What the agent can do

By default every tool is read-only: patients, patient documents (status only), appointments, providers, notes, sessions, templates, eligibility checks, payer search, prior-auth requests, events and workflows, the EHR action catalog and connections, and the key itself (whoami). A tool only appears when the key has its scope. To let the agent change data, add flags to args: Paid tools cost money or reach an outside system: eligibility checks are billable payer requests, note generation uses your Scribe sessions, and prior-auth status checks call Availity. There are no delete tools. Uploads (documents, audio) and the bulk notes export are not available over MCP either; use the CLI or the API for those.

​
Safety model

  • Read-only unless you opt in. Writes need --allow-writes, paid tools also need --allow-paid, and both need the key’s scope. Use a key with only the scopes the agent needs.
  • Results are data, not instructions. Notes, transcripts and patient documents can contain text written by anyone. Every result is wrapped in <healos-data> tags and labeled as untrusted data, and the server tells the agent never to follow instructions found inside it. Your client’s approval prompt for each tool call is still your best control: keep it on for write and paid tools.
  • Bounded results. List tools return at most 25 items per call (10 by default) and every result is capped at 50,000 characters. When a result is cut, it says so and how to get the rest.
  • PHI is not redacted. Results contain real patient information. Only API keys (shown as hlsk_[redacted]) and document file links are replaced, with a visible marker. Use the server only with AI tools your organization has approved for PHI (for example, under a BAA), and only on your own computer.
  • Your key stays out of the conversation. It is never in a tool result or error, and it is only sent over HTTPS to HealOS.

​
Instructions for agents

If you are an AI agent writing code against the HealOS External API:
  1. Read the Quickstart, then the endpoint pages you need. Each endpoint page starts with its scope, rate limit, cost and a Safety box (writes data, safe to retry, outside systems, dry run).
  2. Never ask a user to paste an API key or patient data into a chat. Read the key from the HEALOS_API_KEY environment variable.
  3. Test against a test organization with made-up data. There is no sandbox.
  4. Don’t call billable or outside-system endpoints in loops or retries without a person’s approval: eligibility checks are paid payer requests, and note generation uses the organization’s Scribe sessions.
  5. Branch on HTTP status and code, not the error text. See the Error catalog.
Never paste API keys or real patient information into docs search, the docs assistant or any AI tool. Use placeholders such as hlsk_... and made-up patients.