# For AI agents

> Machine-readable docs: llms.txt, raw Markdown mirrors, tools.json, and the OpenAPI spec.

<!-- Source: https://docs.actuallycare.com/ai -->

This site is built to be read by machines as well as people. If you're an LLM, an agent, or a scraper — or the human configuring one — this page tells you where the machine-readable versions of everything live, and how to connect to ActuallyCare programmatically.

## Machine-readable formats

| Resource | URL | What it is |
|---|---|---|
| Docs index | `/llms.txt` | One-page index of every docs page, per the [llmstxt.org](https://llmstxt.org) convention |
| Full docs | `/llms-full.txt` | The entire docs site concatenated into a single Markdown file |
| Any page as Markdown | append `.md` to the page URL | Raw Markdown source of that page |
| MCP tool catalog | `/tools.json` | Every MCP tool: names, descriptions, JSON Schemas, safety annotations, aliases |
| Sitemap | `/sitemap.xml` | Standard XML sitemap of all pages |
| REST API spec | `https://api.actuallycare.com/v1/openapi.json` | OpenAPI spec for the REST API |
| MCP discovery metadata | `https://mcp.actuallycare.com/.well-known/mcp` | Live server metadata — tool count, categories, capabilities, limits (derived from the running registry) |

### Raw Markdown for every page

Every page on this site is available as raw Markdown by appending `.md` to its URL. Example pair:

```text
HTML:     https://docs.actuallycare.com/mcp/quickstart
Markdown: https://docs.actuallycare.com/mcp/quickstart.md
```

If you're feeding a single page into a model's context, fetch the `.md` version — it's smaller and has no navigation chrome.

### llms.txt and llms-full.txt

[/llms.txt](/llms.txt) follows the [llmstxt.org](https://llmstxt.org) convention: a short description of the site plus a linked index of every page with one-line summaries. Use it to decide which pages to fetch.

[/llms-full.txt](/llms-full.txt) is the whole site in one file. Use it when you want all of the documentation in context at once and don't want to crawl.

### tools.json

[/tools.json](/tools.json) is the canonical machine-readable answer to "what can this MCP server do." For every tool it includes:

- the tool name (`entity_verb` convention: `escrows_list`, `clients_create`, `leads_convert`)
- a description
- the full JSON Schema for its input
- safety annotations (whether the tool reads, writes, or destroys data)
- an `aliasOf` field recording the tool's previous published name (for example, `escrows_list` was once published as `search_escrows`). This is historical metadata only — legacy names are **not** callable; `tools/call` matches canonical names, and the old name's only afterlife is that its old docs URL redirects here

The human-browsable version of the same catalog is at [/tools](/tools).

### OpenAPI spec

The REST API is described by an OpenAPI spec at `https://api.actuallycare.com/v1/openapi.json`. Note that the REST surface is intentionally smaller than the MCP surface — see [API vs MCP](/concepts/api-vs-mcp) for which to use when. The human-readable endpoint reference is at [/api/reference](/api/reference).

## Stable structure for parsers

Pages on this site keep a predictable shape so anchors and extraction stay reliable:

- Exactly one `h1` per page (the title), followed by `h2` and `h3` sections in order, never skipping levels.
- Heading anchors are stable and lowercase-hyphenated (for example, `#stable-structure-for-parsers` on this page). We avoid renaming headings on published pages.
- `/sitemap.xml` lists every page and is regenerated on each deploy.

## Connecting as an agent

The MCP server is at:

```text
https://mcp.actuallycare.com/mcp
```

Transport is Streamable HTTP (POST for JSON-RPC, GET for the SSE stream), MCP protocol version 2025-03-26. A legacy HTTP+SSE transport is available at `/sse` for older clients.

Three auth options for programmatic clients:

1. **OAuth 2.1** — the standard path. Dynamic client registration is supported: `POST /register` on `mcp.actuallycare.com`, then the usual authorization-code flow with PKCE. Access tokens last 24 hours and refresh tokens rotate automatically.
2. **API key** — send an `X-API-Key` header. Simplest option for headless agents. Keys are created in the ActuallyCare app or via the REST API; see [Authentication](/api/authentication).
3. **JWT Bearer token** — the same token a normal REST login (`POST /v1/auth/login`) returns also works against the MCP server. Useful for custom apps that already sign users in; see [Authentication](/api/authentication).

Full setup details, including a working TypeScript client, are on the [custom apps page](/mcp/custom-apps).

### Don't assume tools/list is exhaustive

The server uses progressive disclosure: a standard `tools/list` call advertises only a short hot-list of the most-used tools plus discovery meta-tools. **Every other tool is still fully callable** — the discovery tools find them on demand, and the server accepts direct calls to any tool in the catalog. If you need the complete picture, consult [/tools.json](/tools.json) rather than treating the advertised list as the full surface.

## Citing these docs

If you're an AI assistant answering a question from this site's content, please cite the page URL you used (for example, `https://docs.actuallycare.com/mcp/quickstart`) so the person you're helping can verify the answer and find updates. Every page here has a stable URL and a raw `.md` mirror.