Healsens FHIR MCP

Open-source, conformance-aware MCP server for FHIR R4 and R5.

healsens-fhirmcpis Healsens' MCP implementation for healthcare systems that already expose FHIR and want to make that data usable by AI agents safely, predictably, and with far better schema awareness than a thin proxy can provide. It fronts a configured FHIR base URL and exposes a focused, read-only MCP surface for resource read, typed search, conformance discovery, and safe read-only operations.

The core idea is simple: models perform better when the server helps them understand the target FHIR API. This project embeds version-matched FHIR conformance artifacts and combines them with the liveCapabilityStatementof the connected server so tool calls stay grounded in the shape, semantics, and capabilities of the actual endpoint.

Most healthcare AI integrations fail in predictable ways: generic HTTP wrappers leak too much surface area, models guess at search parameters, and FHIR differences between servers turn otherwise simple tasks into brittle prompt engineering.healsens-fhirmcpis designed to solve that problem directly.

It gives teams a practical MCP layer that is:

- FHIR-aware instead of endpoint-agnostic
- grounded in real conformance metadata instead of prompt-only assumptions
- safe by design with a read-only toolset and a fixed target server
- usable in production integration flows over stdio or native SSE

This repository is open sourced to give implementers a concrete, credible foundation for healthcare MCP deployments, not just a toy example.

A live demo is available for teams evaluating the project. To request access, emailcontact[at]healsens[dot]com.

- Single configured FHIR target server
- Read-only MCP tool surface
- FHIR R4 and R5 support
- Embedded coreStructureDefinitionandOperationDefinitionregistries
- LiveCapabilityStatementfetch with caching
- Typed read and typed search
- Conservative read-only operation invocation
- Discovery and schema resources under thefhirmcp://URI scheme
- Native stdio and SSE hosting modes

- fhir_read
- fhir_search
- fhir_capability_statement
- fhir_structure_definition
- fhir_operation_definition
- fhir_invoke_operation

- fhirmcp://server/guide
- fhirmcp://server/overview
- fhirmcp://server/capability-statement
- fhirmcp://schema/structure-definitions
- fhirmcp://schema/structure-definition/{selector}
- fhirmcp://schema/operation-definitions
- fhirmcp://schema/operation-definition/{selector}
- fhirmcp://server/search-guide

- Conformance first: the server uses embedded FHIR artifacts together with the live targetCapabilityStatementto shape tool behavior.
- Read-only by design: this implementation is intentionally focused on safe retrieval, discovery, and supported read-only operations.
- Predictable integration surface: one configured target, explicit schemas, bounded behavior.
- Real-world interoperability: supports both FHIR R4 and R5, including server-specific capability discovery at startup.

The project deliberately does not try to be a full FHIR SDK, a generic proxy, or a write-capable orchestration layer.
- Copyexamples/config.yamland settarget.base_urlto your FHIR R4 or R5 server.
- Export the bearer token environment variable named in the config if your server requires authentication.
- Sync the vendored conformance artifacts.
- Build and run the server over stdio or SSE.

./scripts/sync_fhir_core_defs.sh go mod tidy go build -o bin/healsens-fhirmcp ./cmd/healsens-fhirmcp FHIRMCP_CONFIG=./examples/config.yaml ./bin/healsens-fhirmcp

Set the transport block inexamples/config.yaml:

server: transport: sse listen_address: 127.0.0.1:8081 sse_path: /sse cors: enabled: true allowed_origins: - http://localhost:8788

go build -o bin/healsens-fhirmcp ./cmd/healsens-fhirmcp FHIRMCP_CONFIG=./examples/config.yaml ./bin/healsens-fhirmcp

Unified access to global medical terminologies: ICD-11, SNOMED CT, LOINC, RxNorm, MeSH. 27 tools for medical coding, terminology lookup, and crosswalk mappings.