fhirHydrant: FHIR MCP Server

A modern, fully configurable, open-source Node.js MCP server for R4+ FHIR APIs. It connects MCP-compatible 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.

• SMART Backend Services auth with JWKS hosting, key rotation, token refresh, and dynamic scopes
• Configurable resource tools for search, direct read, vread, history, and optional metadata-gated CRUD
• Config-driven named operations for clinical data, terminology, IPS, patient matching, validation, and custom workflows
• CapabilityStatement-aware tools, search controls, operation gating, and runtime scope checks
• Token economy features: compact responses, FHIRPath filtering, byte limits, _count shaping, and oversized Bundle retry
• Optional terminology tools, PHI-light audit events (no resource content by default), and stdio or Streamable HTTP transport

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

• Node.js >= 24
• A supported FHIR server
• For SMART auth (default): a SMART Backend Services client registration and an RSA-2048 or EC P-384 private key whose public key is available through JWKS

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"
         }
      }
   }
}

FHIR_ACTIVE_KEY 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:

{
   "mcpServers": {
      "fhirhydrant": {
         "command": "npx",
         "args": ["-y", "fhirhydrant"],
         "env": {
            "MCP_TRANSPORT": "stdio",
            "FHIR_AUTH": "n

... [View full README on GitHub](https://github.com/faulkj/fhirHydrant#readme)