healsens-fhirmcp

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

`healsens-fhirmcp` is 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 live `CapabilityStatement` of the connected server so tool calls stay grounded in the shape, semantics, and capabilities of the actual endpoint.

Why This Project Exists

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-fhirmcp` is 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.

Demo Access

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

What It Provides

• Single configured FHIR target server
• Read-only MCP tool surface
• FHIR R4 and R5 support
• Embedded core `StructureDefinition` and `OperationDefinition` registries
• Live `CapabilityStatement` fetch with caching
• Typed read and typed search
• Conservative read-only operation invocation
• Discovery and schema resources under the `fhirmcp://` URI scheme
• Native stdio and SSE hosting modes

MCP Tools

• `fhir_read`
• `fhir_search`
• `fhir_capability_statement`
• `fhir_structure_definition`
• `fhir_operation_definition`
• `fhir_invoke_operation`

MCP Resources

• `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`

Design Principles

• Conformance first: the server uses embedded FHIR artifacts together with the live target `CapabilityStatement` to 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.

Quick Start

1. Copy examples/config.yaml and set `target.base_url` to your FHIR R4 or R5 server.

2. Export the bearer token environment variable named in the config if your server requires authentication.

3. Sync the vendored conformance artifacts.

4. 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

With `server.transport: stdio`, the binary behaves as a traditional subprocess MCP server over stdin and stdout. With `server.transport: sse`, it exposes a native SSE MCP endpoint at `http://127.0.0.1:8081/sse` by default.

SSE Mode

Set the transport block in examples/config.yaml:

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

Then start the server:

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

Your MCP SSE endpoint will be:

http://127.0.0.1:8081/sse

If the client runs in a browser context, `server.cors` controls cross-origin access for the SSE endpoint and its POST message endpoint. `allowed_origins` should contain the exact browser origins you trust.

Development

• `make sync-core` refreshes the vendored FHIR R4 and R5 artifacts.
• `make build` builds the server binary for stdio or SSE mode.
• `make test` runs unit and integration tests.