> ## Documentation Index
> Fetch the complete documentation index at: https://docs.healos.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Docs for AI agents

> Machine-readable docs for coding assistants, and the HealOS MCP server for AI agents

These docs are published in forms that AI coding assistants and agents can
read directly.

| What | Where | Use it for |
| - | - | - |
| `llms.txt` | [docs.healos.ai/llms.txt](https://docs.healos.ai/llms.txt) | An index of every page with a one-line summary |
| `llms-full.txt` | [docs.healos.ai/llms-full.txt](https://docs.healos.ai/llms-full.txt) | Every page in one file |
| Markdown pages | Add `.md` to any page URL, for example [docs.healos.ai/quickstart.md](https://docs.healos.ai/quickstart.md) | One page as plain Markdown |
| OpenAPI spec | The **Copy page** menu on any [API Reference](https://docs.healos.ai/api-reference.md) page | Generating a typed client |
| Docs search (MCP) | `https://docs.healos.ai/mcp` | Letting an MCP client search these docs |

Every page also has a **Copy page** menu to copy it as Markdown or open it
in ChatGPT or Claude.

> [!NOTE]
>
> 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](https://modelcontextprotocol.io) 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](https://docs.healos.ai/cli.md) and uses the key you signed in with, with that key's
scopes, rate limits and audit log.

> [!NOTE]
>
> `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:

   ```bash theme={null}
   npx @healos/cli login
   ```

   The key is read-only unless you ask for more scopes. See [Sign in](https://docs.healos.ai/cli.md#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).

```json Claude Desktop theme={null}
{
  "mcpServers": {
    "healos": {
      "command": "npx",
      "args": ["-y", "@healos/cli", "mcp"]
    }
  }
}
```

```json Cursor theme={null}
{
  "mcpServers": {
    "healos": {
      "command": "npx",
      "args": ["-y", "@healos/cli", "mcp"]
    }
  }
}
```

```bash Claude Code theme={null}
claude mcp add healos -- npx -y @healos/cli mcp
```

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`:

| Flag | Adds | Also needs |
| - | - | - |
| `--allow-writes` | `create_patient`, `update_patient`, `create_appointment`, `update_appointment`, `assign_session_patient` | The key's write scope |
| `--allow-writes --allow-paid` | `run_eligibility_check`, `generate_note_from_text`, `regenerate_session_note`, `generate_note_from_documents`, `extract_document_text`, `check_prior_auth_status` | The key's write scope, and `confirm: true` on every call |

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](https://docs.healos.ai/quickstart.md), 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](https://docs.healos.ai/test-mode.md) 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](https://docs.healos.ai/errors.md).

> [!WARNING]
>
> 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.