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.