smart-fhir
It provides a read-only, stdio MCP connector to allowlisted FHIR R4/SMART sandboxes for discovery, auth status, one-page searches, and reads—no writes or invented patients.
Discover SMART configuration at
{iss}/.well-known/smart-configurationfor allowlisted ISS URLs.Report auth mode, ISS, R4 lock, write=off, token presence, and discovery status without exposing secrets.
Search only Patient, Observation, Condition, MedicationRequest, and Encounter; returns one page with
_countdefault 10/max 50, preserving empty Bundles.Read a specific allowlisted resource by ID; a 404 remains not found rather than a fabricated resource.
Use only supported ISS sandboxes and auth modes (
open,bearer,backend_jwt); no CRUD, bulk, App Launch, production EHR, PHI, or HTTP binding.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@smart-fhir Search for Patients with family name Smith"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
smart-fhir
A connector that will not invent a patient.
Install · Tools · How it works · Limits
Install
stdio only. After the TypeScript build, add a local connector:
name: smart-fhir
command: node
args: dist/index.jsnpm install
npm run buildEnv for that add (defaults, not secrets):
FHIR_ISS = https://launch.smarthealthit.org/v/r4/fhir
FHIR_VERSION = R4
FHIR_AUTH_MODE = open
FHIR_WRITE = off
FHIR_AUDIT_PATH = ./audit/audit.jsonlDo not put secret values in the repo. No public HTTP port. Do not bind TCP.
Vendor sandbox (Epic / Oracle Health) is backend_jwt plus a registered non-production client_id. See docs/SANDBOX-EMR.md. Epic sandbox prove progress log: docs/EPIC-SANDBOX-PROVE-PROGRESS.md.
Morning shortcut (same env)
npx -y tsx src/index.tsSee package.json scripts: install, build, test, prove, keygen.
Related MCP server: practice-fusion-mcp
Tools
Four tools. No create / update / delete.
Tool | Action |
| GET |
|
|
| GET |
| GET |
resourceType allowlist: Patient | Observation | Condition | MedicationRequest | Encounter. Anything else → { ok: false, error: "resourceType not in v1 allowlist" }.
How it works
FHIR_VERSION must be R4. Anything else refuses to start.
What | URL | How to read it |
FHIR index (published page is R5 5.0.0) | Official index only. Not implemented. | |
FHIR R4 (v1) | FHIR Release 4, 4.0.1. Resource model. | |
SMART App Launch 2.2.0 (STU 2.2) | Current published SMART IG. Based on FHIR R4. | |
App launch + authorization | Discovery, standalone/EHR launch, PKCE, token. App Launch (code+PKCE) is out of v1. | |
Backend Services | client_credentials + private-key JWT. |
ISS allowlist (trailing slash stripped, anything else refused):
https://launch.smarthealthit.org/v/r4/fhir(default)https://r4.smarthealthit.orghttps://hapi.fhir.org/baseR4https://fhir.epic.com/interconnect-fhir-oauth/api/FHIR/R4(Epic sandbox)https://fhir-open.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d(Oracle open sandbox)https://fhir-ehr-code.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d(Oracle secure sandbox)
Production EHR ISS is refused. A new ISS needs a review first.
FHIR_AUTH_MODE | Behavior |
| Discover, then FHIR GET without Authorization. Discovery 404 is not fatal in open (logged; continue). 401/403 FHIR → |
| Same discovery. FHIR GET with Authorization Bearer token. |
| Requires |
App Launch (code+PKCE) is out. FHIR_REDIRECT_URI is reserved and unused.
Auth failure shape: { ok: false, http_status, issue?, error? }. Never a synthetic Patient.
FHIR_WRITE defaults off. v1 has no write tools even if someone sets on. Writes never POST AuditEvent to FHIR.
Name | Default | Notes |
FHIR_ISS | default launcher R4 | Must stay allowlisted |
FHIR_VERSION | R4 | Reject anything else |
FHIR_AUTH_MODE | open | open / bearer / backend_jwt |
FHIR_WRITE | off | Writes stay off in v1 |
FHIR_AUDIT_PATH |
| Append-only JSONL |
FHIR_ACCESS_TOKEN | unset | Bearer only |
FHIR_CLIENT_ID | unset | Backend Services |
SMART_CLIENT_ID | unset | Alias of FHIR_CLIENT_ID |
FHIR_PRIVATE_KEY_PEM | unset | Backend Services JWT |
FHIR_JWT_KID | unset | Required in backend_jwt |
FHIR_JWKS_URL | unset | Optional |
FHIR_SCOPE | five system/*.rs types | JWT mode override |
FHIR_REDIRECT_URI | unset | Reserved for later App Launch |
Audit lines: ts, tool, iss, mode, resourceType, id?, http_status, entry_count?. No resource body, no token, no PEM, no name/MRN query values.
Limits
R5 / R4B as default. Extra resource types. CRUD. Bulk. App Launch browser/PKCE.
Real EHR / real PHI. Production deploy. Public bind or Streamable HTTP.
momentum / fhirhydrant / Atrium / Pinecone / Medplum.
Not a medical product. Does not diagnose, treat, or store PHI.
No PHI. No live EHR.
Available Tools
4 toolsfhir_auth_statusFHIR auth statusA
Report mode, ISS, R4 lock, write=off, token_present, discovery_ok. Never prints token or PEM.
Inputs: no named parameters.
fhir_readFHIR readB
GET {iss}/{resourceType}/{id} as FHIR R4. 404 is not found, not a made-up resource. Same resourceType allowlist as search.
Inputs: id (required), resourceType (required), iss.
fhir_searchFHIR searchA
GET {iss}/{resourceType} as FHIR R4 searchset. resourceType allowlist: Patient, Observation, Condition, MedicationRequest, Encounter. _count default 10 max 50. One page only. Does not invent Patients.
Inputs: resourceType (required), iss, params.
smart_discoverSMART discoverA
GET {iss}/.well-known/smart-configuration (SMART App Launch 2.2.0). Optional iss must be v1-allowlisted. Does not invent endpoints.
Inputs: iss.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool targets a distinct function: smart_discover retrieves server metadata, fhir_auth_status reports client-side authentication state, fhir_search performs list queries, and fhir_read fetches individual resources. There is no overlap or ambiguity between the four operations.
Tools use a consistent prefix pattern (smart_ for auth/discovery, fhir_ for data operations) and each suffix clearly indicates the action (discover, auth_status, search, read). While the prefixes differ by domain, the overall structure is predictable and not chaotic.
Four tools is on the lower end but appropriate for a narrowly scoped read-only FHIR access server focused on discovery and basic querying. It avoids bloat while covering the primary use cases.
The server covers read and search for a limited set of resources, but lacks pagination (only one page), search parameters beyond resource type, and a capability statement. Given the explicit read-only nature, core operations are present but notable gaps exist in search depth and server metadata.
Maintenance
Related MCP Connectors
Read-only ArcadeOps discovery for developer docs, OAuth, OpenAPI and synthetic sandbox.
Synthetic EHR: medications, labs, conditions, allergies, immunizations, FHIR R4. No API key.
FHIR R4 health records for AI: people connect their own record with consent; free FHIR sandbox.
Read-only U.S. lab-test catalog, collection-site search, and reference-range context.
Related MCP Servers
- AlicenseAqualityCmaintenanceRead-only MCP server for licensed Healthpoint HL7 FHIR API access.101Apache 2.0
- AlicenseAqualityBmaintenanceEnables read-only FHIR access to Practice Fusion EHR to search patients, appointments, conditions, medications, and lab results.134MIT
- AlicenseAqualityDmaintenanceProvides safe read-only access to synthetic healthcare data via FHIR R4, enabling AI assistants to search patients, retrieve vitals, and summarize conditions using a public sandbox.4MIT
- FlicenseNot gradedqualityBmaintenanceConnects MCP clients to FHIR R4+ clinical APIs over SMART on FHIR v2 Backend Services, exposing resources, named operations, terminology lookup, and pagination as configurable tools. It adds metadata- and scope-aware search/CRUD, compact responses with FHIRPath filtering, safe pagination, audit events, and bundle execution.117 npm18-