FHIR Tools MCP Server

An MCP (Model Context Protocol) server exposing FHIR resource validation, synthetic test fixture generation, and HIPAA-safe logging review as tools an AI agent can call directly.

What it does

Three tools:

• fhir_validate_resource — validates a FHIR resource JSON payload: checks resourceType presence, id format, required fields for known resource types (Observation, Encounter, Condition, MedicationRequest), reference field format (ResourceType/id), and whether Coding system URIs are recognized (LOINC, SNOMED CT, ICD-10, RxNorm) rather than placeholder/made-up values.

• fhir_generate_test_fixture — generates synthetic FHIR test data (Patient, Observation, Condition) for use in tests. All generated data is obviously fake (TEST- prefixed ids, placeholder names) — this tool never uses or produces real patient data.

• fhir_check_hipaa_safe_logging — reviews code for patterns that could leak PHI into application logs: logging full request/response bodies, logging clinical resource variables directly (vs. just their id), and exception handlers that log raw request context.

Related MCP server: Heavenly Health Protocol

Why an MCP server instead of just asking an LLM

FHIR schema rules (required fields per resource type, valid coding systems, reference formats) are precise and well-documented — the kind of thing that should be checked deterministically, not re-derived by an LLM from training data each time (which risks subtly wrong or outdated schema assumptions). Wrapping this as MCP tools means an agent gets a guaranteed-correct validation result and can iterate on a payload until it actually passes, rather than trusting a plausible-sounding but unverified answer.

Running it

pip install -r requirements.txt
python server.py

Connect it to Claude Code, Claude Desktop, or any MCP client via the client's MCP server config (stdio transport by default).

Example: generating a test fixture

Request: generate an Observation fixture for scenario "blood pressure reading"

Output:

# Scenario: blood pressure reading
{
  "resourceType": "Observation",
  "id": "TEST-4f9a1b2c",
  "status": "final",
  "code": {
    "coding": [{"system": "http://loinc.org", "code": "85354-9", "display": "Blood pressure panel"}]
  },
  "subject": {"reference": "Patient/TEST-8e2d0a91"},
  "effectiveDateTime": "2026-08-11",
  "_note": "SYNTHETIC TEST DATA -- not a real observation"
}

Tests

pytest -v

13 tests covering validation (valid/invalid resources, malformed references, unknown coding systems), fixture generation, and logging safety review.

Limitations

• Required-field checks cover a handful of common resource types, not the full FHIR resource catalog.

• Coding system recognition is an allowlist of common systems (LOINC, SNOMED CT, ICD-10, RxNorm, etc.) — legitimate but less common systems will be flagged as "unrecognized" and need manual confirmation.

• Logging safety checks are pattern-based static analysis, not a full data-flow analysis — treat findings as a starting point for review, not a compliance guarantee.

Possible extensions

• Expand required-field rules to cover more FHIR resource types

• Add a tool that checks a resource against a specific FHIR Implementation Guide / profile, not just base FHIR structure

• Add a tool that redacts PHI fields from a resource for safe logging, rather than just flagging unsafe patterns