# Health Data Safe for AI agents

> Documentation for AI agents, and the people who use them, working with Health Data Safe (HDS): the open, consent-based health data infrastructure of a Swiss non-profit foundation, where each person owns their health record and decides who may read or add to it. It covers connecting an AI assistant to a person's HDS account through the HDS MCP server, recording data with the HDS data model, and building apps with the hds-lib JavaScript library.

An AI assistant connects to an HDS account in one of two ways. The remote connector needs no install: the person adds it in Claude.ai, ChatGPT or Claude Code (one connector URL per production region, shown on the "AI assistant" tab of https://account.hds.ngo), signs in with OAuth on HDS and approves the access on a consent screen; see the connect-remote page below. The local HDS MCP server runs on the person's own computer (stdio transport, Node.js 20 or newer) with MCP-capable clients such as Claude Desktop, started with `npx -y github:healthdatasafe/hds-mcp-js`; see the install page below. It defaults to the demo platform, and it is the one to use for imports that create new streams; writing to a real (production) account through it needs the person's explicit request.

If the person wants to build an app or a script rather than have you work on their data, they do not need the MCP server: their code uses hds-lib (see "Building apps").

## Start here

- [bootstrap.txt](https://agents.datasafe.dev/bootstrap.txt): instructions to follow when a person asks you to guide them with HDS: scope the project first, install the MCP server, tell them who sees what before reading any record, first connection.
- [llms-full.txt](https://agents.datasafe.dev/llms-full.txt): the complete technical reference in one file: data model (events, streams, items), the itemDef-first rule, the MCP tools, hds-lib, REST, bulk imports, worked examples, production guardrails and error messages.

## Pages

- [HDS for AI agents](https://agents.datasafe.dev/): overview and the short prompt a person pastes into their assistant.
- [Connect from Claude.ai / ChatGPT](https://agents.datasafe.dev/connect-remote/): add HDS as a remote connector, per production region; client IDs and raw mode (sign in by link).
- [Install the MCP server](https://agents.datasafe.dev/install/): requirements, the client configuration entry, troubleshooting.
- [Connect & permissions](https://agents.datasafe.dev/connect/): the browser sign-in, access levels, production guardrails, what the model provider sees.
- [Recording data right](https://agents.datasafe.dev/data/): look data up in the HDS data model before writing it, structured events instead of notes, the bulk import contract.
- [Building apps (hds-lib)](https://agents.datasafe.dev/build/): when the goal is a web page, an app or a Node program.
- [Partner services (easy-connect)](https://agents.datasafe.dev/partner-services/): let an app connect a person's partner service (Mira, Tempdrop) and show its sync status.
- [Feedback & issues](https://agents.datasafe.dev/feedback/): the single tracker for everything agent-related, including data that HDS has no item for yet ([data model gap template](https://github.com/healthdatasafe/site-agents/issues/new?template=data-model-gap.md)).

## Optional

- [HDS data model pack](https://model.datasafe.dev/pack.json): the machine-readable catalogue of items, streams and event types.
- [Data model browser](https://model-browser.datasafe.dev): the same catalogue for humans.
- [hds-mcp-js on GitHub](https://github.com/healthdatasafe/hds-mcp-js): source of the MCP server.
- [hds-lib-js on GitHub](https://github.com/healthdatasafe/hds-lib-js): the JavaScript library for HDS apps.
- [Developer documentation](https://docs.datasafe.dev/developers/): the general HDS developer docs.
- [Health Data Safe Foundation](https://www.healthdatasafe.org): the foundation's website (its own index: https://www.healthdatasafe.org/llms.txt).