---
name: iblai-connect-fhir
description: "Read and write HL7 FHIR data through the FHIR RESTful API (R4, 4.0.1) and SMART App Launch and expose it to an ibl.ai agent as an MCP tool. Use when the user asks an agent to work with HL7 FHIR data, or to set up an HL7 FHIR MCP connection on ibl.ai."
metadata:
  kind: guide
---

# HL7 FHIR connector for AI agents

> A starting point maintained on ibl.ai at https://ibl.ai/developer/connectors/fhir — not part of the iblai/vibe repository. Checked against HL7 International's documentation on October 20, 2026; test it against your own HL7 FHIR setup before you rely on it.

FHIR (Fast Healthcare Interoperability Resources) is HL7's standard for exchanging health data as resources such as Patient, Observation and Condition over a REST API. R4 (4.0.1) is widely implemented; 5.0.0 is the current release.

## Auth & conventions

- **API:** FHIR RESTful API (R4, 4.0.1) and SMART App Launch (FHIR R4). Defines read, vread, update, patch, delete, history, create, search, capabilities (GET [base]/metadata) and batch/transaction interactions on [base]/[type]/[id], in JSON, XML or Turtle.
- **Base URL:** [base]/[type]/[id] where [base] is each server's Service Base URL
- **Access:** Public, self-serve. The specification is free to read. Credentials come from each FHIR server operator (an EHR vendor or health system), usually by registering a SMART client.
- **Auth:** SMART App Launch (OAuth 2.0 authorization code); SMART Backend Services (JWT). SMART App Launch 2.2.0 defines EHR and standalone launch, discovery at .well-known/smart-configuration, and scopes like patient/Observation.rs. Backend Services use client_credentials with a jwt-bearer client assertion.
- **Limits:** Search results return as a Bundle of type searchset, paged with self, first, previous, next and last links. Backend Services access tokens SHOULD NOT exceed 300 seconds (expires_in).
- Keep HL7 FHIR credentials in environment variables or the ibl.ai credential store. Never print a token in chat and never commit one to a file.
- Destructive or outward-facing calls are marked **Confirm with the user first** — do.

## Reads

- **Read and vread** — GET [base]/[type]/[id] returns the current version; vread returns a specific version.
- **Search** — GET or POST search on a type; results come back as a Bundle of type searchset.
- **History** — History of changes at instance, type or system level.
- **Capabilities** — GET [base]/metadata returns the server's CapabilityStatement.

## Writes

- **Create** — POST [base]/[type] creates a resource with a server-assigned id.
- **Update and patch** — PUT [base]/[type]/[id] replaces a resource (or creates it); PATCH changes part of it.
- **Delete** — DELETE [base]/[type]/[id]; later reads return 410 Gone. **Confirm with the user first.**
- **Batch and transaction** — POST a Bundle to [base] to run several operations, atomically for a transaction. **Confirm with the user first.**

## Expose it to an ibl.ai agent (MCP)

HL7 International did not publish an MCP server of its own when this skill was checked. Host a small MCP server that wraps the calls above, then register it below.

First install the ibl.ai platform skills and connect your organization (writes `IBLAI_ORG`, `IBLAI_USERNAME` and `IBLAI_API_KEY` to `.env`):

```bash
npx skills add iblai/vibe --all
# then, in your coding agent:
/iblai-api-login
```

Every call below sends `Authorization: Api-Token $IBLAI_API_KEY`.

1. **Register the server** — `POST https://api.iblai.app/dm/api/ai-mentor/orgs/$IBLAI_ORG/users/$IBLAI_USERNAME/mcp-servers/` with `name`, `url`, `transport` (`sse` | `websocket` | `streamable_http`) and `auth_type` (`none` | `token` | `oauth2`). Capture the returned `id`.
   - HL7 FHIR supports per-user OAuth: `auth_type=oauth2` with `auth_scope=user` and a linked `oauth_service` makes each person connect their own account in the chat. It needs an `auth_{provider}` credential in the organization's credential store first.
2. **Create the connection** — `POST https://api.iblai.app/dm/api/ai-mentor/orgs/$IBLAI_ORG/users/$IBLAI_USERNAME/mcp-server-connections/` with `server`, `scope` (`platform` | `mentor` | `user`), `auth_type`, and either `credentials` + `authorization_scheme` or a `connected_service` id for OAuth. Credentials are masked on read; never send a masked value back.
3. **Enable it on the agent** — `GET https://api.iblai.app/dm/api/ai-mentor/orgs/$IBLAI_ORG/users/$IBLAI_USERNAME/mentors/{agent_id}/settings/`, add `mcp-tool` to `tool_slugs` and the server id to `mcp_servers`, then `PATCH` the full lists back. They are replaced, not merged.

Full reference: https://ibl.ai/developer/platform/mcp/mcp-connections and the `/iblai-api-agent-mcp` skill.

## Example prompts

- "Read this FHIR server's CapabilityStatement and tell me which resources it supports."
- "Search Observation for LOINC 4548-4 for patient 123 and chart the results."
- "Build a transaction Bundle that creates this Patient and two Conditions."
- "Check the server's SMART configuration and list supported scopes."

## Guardrails

- FHIR is a format, not a data store, but records exchanged with US providers are usually HIPAA protected health information (PHI); servers enforce access with SMART scopes.
- Request the narrowest HL7 FHIR scopes or role the task needs, and prefer a read-only credential for agents that only answer questions.
- Return the fields the user asked for, not whole records; do not paste personal data into chat that the user did not request.
- Before any write, show the user exactly what will change and wait for a yes.
- Respect the documented limits above: page through results and back off on rate-limit responses instead of retrying in a loop.

## References

- FHIR R4 specification: https://hl7.org/fhir/R4/
- FHIR R4 RESTful API: https://hl7.org/fhir/R4/http.html
- SMART App Launch: https://hl7.org/fhir/smart-app-launch/
- This connector on ibl.ai: https://ibl.ai/developer/connectors/fhir
- ibl.ai MCP server connections: https://ibl.ai/developer/platform/mcp/mcp-connections