Fhirhydrant MCP server

fhirHydrant: FHIR MCP Server

A modern, fully configurable, open-source Node.js Model Context Protocol (MCP) server for R4+ FHIR APIs. It connects MCP-compatible LLM AI clients to clinical data over SMART on FHIR v2 Backend Services using signed JWT client credentials.

fhirHydrant turns FHIR resources, named operations, terminology lookups, and pagination into MCP tools. The default resources and operations are starting points: resources, operations, search controls, instructions, and messages can be expanded, trimmed, or replaced through config files without source changes.

and dynamic scopes

• SMART Backend Services auth with JWKS hosting, key rotation, token refresh,

optional metadata-gated CRUD

• Configurable resource tools for search, direct read, vread, history, and

matching, validation, and custom workflows

• Config-driven named operations for clinical data, terminology, IPS, patient

runtime scope checks

• CapabilityStatement-aware tools, search controls, operation gating, and

_count shaping, and oversized Bundle retry

• Token economy features: compact responses, FHIRPath filtering, byte limits,

default), and stdio or Streamable HTTP transport

• Optional terminology tools, PHI-light audit events (no resource content by

Note: FHIR data returned through MCP tool calls may contain PHI.

Make sure your MCP client's transcript storage and logging behavior match

your compliance requirements.

Contents

• Quick Start
• Tools
• Metadata And Scope Gating
• Token Economy And Response Shaping
• Audit Events
• SMART Backend Auth And Keys
• Environment Variables
• FHIR Version Support
• Customizing Tools And Messages
• Transports
• Deployment Examples
• Development

Quick Start

Requirements

RSA-2048 or EC P-384 private key whose public key is available through JWKS

• Node.js >= 24
• A supported FHIR server
• For SMART auth (default): a SMART Backend Services client registration and an

To run against a public, unauthenticated FHIR test server, set FHIR_AUTH=none and skip the client and key entirely (see Unauthenticated Access).

The stdio transport usually needs an externally hosted JWKS URL. The built-in /jwks endpoint is available only when fhirHydrant runs over HTTP with SMART auth.

Install

# install globally
npm install -g fhirhydrant

# or run without installing
npx fhirhydrant

Run from source:

git clone https://github.com/faulkj/fhirhydrant.git
cd fhirhydrant
npm install
npm run build

MCP Client Config

For desktop MCP clients, stdio is usually the simplest transport:

{
   "mcpServers": {
      "fhirhydrant": {
         "command": "npx",
         "args": ["-y", "fhirhydrant"],
         "env": {
            "MCP_TRANSPORT": "stdio",
            "FHIR_BASE_URL": "https://fhir.example.org",
            "FHIR_CLIENT_ID": "your-client-id",
            "FHIR_ACTIVE_KEY": "LS0tLS1CRUdJTi...base64-of-your-pem...",
            "FHIR_JWKS_URL": "https://example.org/.well-known/jwks.json"
         }
      }
   }
}

FHIRACTIVEKEY is your PKCS#8 private key (RSA or EC P-384), base64-encoded. The kid is derived automatically at startup via a truncated JWK Thumbprint and logged to the console.

Unauthenticated Access

To point fhirHydrant at a public, unauthenticated FHIR endpoint (handy for testing against open sandboxes), set FHIR_AUTH=none. No client ID or signing key is required, no token is requested, and requests are sent without an Authorization header:

Shortened. The full README is on GitHub.