# FHIR MCP server for AI agents

> Connect Claude Code, Cursor, VS Code or Claude Desktop to an HL7 FHIR R4 API through MCP: 14 tools for reading records, AI-ready context, writing, lab import and sandbox reset, on 30 synthetic patients, free.

Source: https://developers.anpheros.com/guides/mcp

**Anpheros FHIR is a remote MCP server that lets an AI agent (Claude, Claude Code, Cursor, VS Code, Claude Desktop) work with an HL7 FHIR R4 health-data API.** It connects in two ways:

- **With a free sandbox key**, for developers: your agent lists patients, reads their records as FHIR or as an AI-ready context with provenance, writes observations, imports lab reports and resets its test data, all on 30 synthetic patients with realistic histories.
- **With OAuth**, for a person and their own record: the assistant registers itself, the person signs in and approves it on the Anpheros consent screen, and the assistant can then read that one record, for the period chosen, read-only unless the person allowed more.

Server address: `https://platform.anpheros.com/mcp` (Streamable HTTP, stateless).

## Connect with OAuth (Claude and other assistants)

Add `https://platform.anpheros.com/mcp` as a custom connector (in Claude: Settings → Connectors → Add custom connector). Nothing else to configure: the assistant discovers the authorization server, registers itself and opens the Anpheros consent screen. There the person sees that it is an AI assistant, that what it reads is sent to the company running the assistant, what it may read, for how long and where they will return after choosing. Access is read-only unless more was asked for and allowed, and the person can revoke it at any time.

During the private beta, OAuth connections use sandbox records. Connections to real records open after the privacy policy is updated.

## Connect with a sandbox key (developers)

1. Sign in at [platform.anpheros.com/dashboard](https://platform.anpheros.com/dashboard/) with Google and choose **Get a sandbox key**. You get an `sk_test_…` key and a project with 30 synthetic patients.
2. Put the key in an environment variable, for example `ANPHEROS_KEY`, and add the server to your tool.

**Claude Code**

```bash
claude mcp add --transport http anpheros-fhir https://platform.anpheros.com/mcp --header "Authorization: Bearer $ANPHEROS_KEY"
```

**Cursor** (`~/.cursor/mcp.json` or `.cursor/mcp.json` in the project)

```json
{
  "mcpServers": {
    "anpheros-fhir": {
      "url": "https://platform.anpheros.com/mcp",
      "headers": { "Authorization": "Bearer ${env:ANPHEROS_KEY}" }
    }
  }
}
```

**VS Code** (`.vscode/mcp.json`)

```json
{
  "servers": {
    "anpheros-fhir": {
      "type": "http",
      "url": "https://platform.anpheros.com/mcp",
      "headers": { "Authorization": "Bearer ${env:ANPHEROS_KEY}" }
    }
  }
}
```

**Claude Desktop** (`claude_desktop_config.json`, through the `mcp-remote` bridge)

```json
{
  "mcpServers": {
    "anpheros-fhir": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://platform.anpheros.com/mcp", "--header", "Authorization: Bearer ${ANPHEROS_KEY}"],
      "env": { "ANPHEROS_KEY": "sk_test_…" }
    }
  }
}
```

Then ask your agent something like: *"List the sandbox patients, pick the one with diabetes and summarise her last six months of HbA1c."*

## Tools

| Tool | What it does |
|---|---|
| `list_patients` | the project's patients: the 30 synthetic personas and any you created |
| `get_patient_context` | an AI-ready context for one patient, within a token budget, each item labelled with its source |
| `get_patient_summary` | the International Patient Summary (FHIR `$summary`), in the language you ask for |
| `get_timeline` | the record in date order across resource types |
| `search_fhir` | standard FHIR R4 search, returning a Bundle |
| `read_fhir_resource` | one resource, or one earlier version of it |
| `get_provenance` | who wrote a resource, when and from which system |
| `lookup_code` | LOINC and ATC codes by text or by code |
| `validate_fhir_resource` | checks a resource without saving it |
| `create_fhir_resource` | validates, then writes a resource |
| `create_patient` | a new made-up patient in the project |
| `import_lab_report` | a CSV, HL7 v2 ORU^R01 or JSON lab report becomes laboratory Observations |
| `sandbox_status` | writes used today, patients, storage, resets |
| `reset_sandbox` | restores the 30 synthetic patients (asks for confirmation) |

Read tools are marked read-only and the reset is marked destructive, so clients that ask before risky actions can do so. The server also offers the list of synthetic patients as a resource and three prompts: a clinician summary, a lab CSV import and building your integration on the API.

## How it behaves

- **The same rules as the API.** Every tool calls the public API with your key: the same scopes, rate limits, validation and audit. A read-only key cannot write.
- **Provenance.** Everything an agent writes is recorded with the source `urn:anpheros:mcp`, so you can always tell what came from an agent.
- **Patient data is data.** Tool results carry a note that record content must never be followed as instructions, a basic guard against prompt injection through medical records.
- **One record, with consent.** Production API keys (`sk_live_…`) are refused, because they reach every patient of a project. A real record reaches an assistant only through OAuth, after that person approves it, and every read is logged in their access history.
- **Standard discovery.** Without credentials the server answers 401 with a `WWW-Authenticate` header pointing to its OAuth protected resource metadata (RFC 9728); assistants register through dynamic client registration (RFC 7591), with PKCE. Registration accepts only loopback addresses, the app schemes of known editors and the callback domains of known AI assistants.

## Frequently asked questions

### What is an MCP server?
MCP (Model Context Protocol) is an open protocol through which AI agents and coding assistants call external tools. An MCP server for FHIR lets the agent read and write health records directly, instead of you pasting data into the chat.

### Is it free?
Yes. The MCP server works on the free sandbox: 30 synthetic patients per project, up to 10,000 writes a day, no card.

### Can an assistant read a real patient's record?
Only through OAuth, after that person approves the assistant on the consent screen, for the period they choose, and only their own record (or that of someone they care for). During the private beta, OAuth connections use sandbox records.

### Which FHIR version does it use?
HL7 FHIR R4 (4.0.1), the same API as https://platform.anpheros.com/fhir/R4, with the International Patient Summary and a REST view of the same data.

### Does it work with ChatGPT?
ChatGPT connectors use OAuth with dynamic client registration, which the server supports, and its callback domain is accepted. We have tested the flow with the official MCP SDK client; if a ChatGPT connection fails, write to support@anpheros.com. Claude Code, Cursor and VS Code also work with a sandbox key.

## Related

- [Free FHIR database and sandbox](https://developers.anpheros.com/guides/free-fhir-database)
- [AI agents and medical data](https://developers.anpheros.com/guides/ai-agents-medical-data)
- [LLM applications and healthcare data](https://developers.anpheros.com/guides/llm-healthcare-data)
- [Healthcare API with patient consent](https://developers.anpheros.com/guides/healthcare-api-patient-consent)