fhirHydrant: FHIR MCP Server

Ein moderner, vollständig konfigurierbarer Open-Source-Node.js-MCP-Server für R4+ FHIR-APIs. Er verbindet MCP-kompatible Clients mit klinischen Daten über SMART on FHIR v2 Backend Services mit signierten JWT-Client-Anmeldedaten.

fhirHydrant verwandelt FHIR-Ressourcen, benannte Operationen, Terminologie-Nachschlagen und Pagination in MCP-Tools. Die Standardressourcen und -operationen sind Ausgangspunkte: Ressourcen, Operationen, Suchsteuerungen, Anweisungen und Nachrichten können über Konfigurationsdateien ohne Quellcodeänderungen erweitert, reduziert oder ersetzt werden.

• SMART-Backend-Services-Authentifizierung mit JWKS-Hosting, Schlüsselrotation, Token-Erneuerung und dynamischen Scopes

• Konfigurierbare Ressourcen-Tools für Suche, direkte Lesevorgänge, vread, Verlauf und optionale metadatengesteuerte CRUD-Operationen

• Konfigurationsgesteuerte benannte Operationen für klinische Daten, Terminologie, IPS, Patientenabgleich, Validierung und benutzerdefinierte Workflows

• CapabilityStatement-bewusste Tools, Suchsteuerungen, Operations-Gating und Laufzeit-Scope-Prüfungen

• Token-Ökonomie-Funktionen: kompakte Antworten, FHIRPath-Filterung, Byte-Limits, _count-Formung und Wiederholung bei übergroßen Bundles

• Optionale Terminologie-Tools, PHI-arme Audit-Ereignisse (standardmäßig ohne Ressourceninhalt) und stdio- oder Streamable-HTTP-Transport

Hinweis: FHIR-Daten, die über MCP-Tool-Aufrufe zurückgegeben werden, können PHI enthalten. Stellen Sie sicher, dass die Transkriptspeicherung und Protokollierung Ihres MCP-Clients Ihren Compliance-Anforderungen entsprechen.

Inhalt

• Schnellstart

• Tools

• Metadaten- und Scope-Gating

• Token-Ökonomie und Antwortformung

• Audit-Ereignisse

• SMART-Backend-Auth und Schlüssel

• Umgebungsvariablen

• FHIR-Versionsunterstützung

• Anpassen von Tools und Nachrichten

• Transports

• Bereitstellungsbeispiele

• Entwicklung

Related MCP server: smart-mcp-server

Schnellstart

Anforderungen

• Node.js >= 24

• Ein unterstützter FHIR-Server

• Für SMART-Auth (Standard): eine SMART-Backend-Services-Client-Registrierung und ein RSA-2048- oder EC-P-384-privater Schlüssel, dessen öffentlicher Schlüssel über JWKS verfügbar ist

Um gegen einen öffentlichen, nicht authentifizierten FHIR-Testserver zu laufen, setzen Sie FHIR_AUTH=none und überspringen Sie Client und Schlüssel vollständig (siehe Nicht authentifizierter Zugriff).

Der stdio-Transport benötigt normalerweise eine extern gehostete JWKS-URL. Der integrierte /jwks-Endpunkt ist nur verfügbar, wenn fhirHydrant über HTTP mit SMART-Auth läuft.

Installation

# install globally
npm install -g fhirhydrant

# or run without installing
npx fhirhydrant

Aus dem Quellcode ausführen:

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

MCP-Client-Konfiguration

Für Desktop-MCP-Clients ist stdio normalerweise der einfachste 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 ist Ihr PKCS#8-privater Schlüssel (RSA oder EC P-384), base64-kodiert. Die kid wird beim Start automatisch über einen gekürzten JWK-Thumbprint abgeleitet und in der Konsole protokolliert.

Nicht authentifizierter Zugriff

Um fhirHydrant auf einen öffentlichen, nicht authentifizierten FHIR-Endpunkt zu richten (praktisch zum Testen gegen offene Sandboxes), setzen Sie FHIR_AUTH=none. Es ist keine Client-ID oder Signaturschlüssel erforderlich, kein Token wird angefordert, und Anfragen werden ohne Authorization-Header gesendet:

{
   "mcpServers": {
      "fhirhydrant": {
         "command": "npx",
         "args": ["-y", "fhirhydrant"],
         "env": {
            "MCP_TRANSPORT": "stdio",
            "FHIR_AUTH": "none",
            "FHIR_SERVER_URL": "https://hapi.fhir.org/baseR4"
         }
      }
   }
}

Tools

fhirHydrant registriert Tools aus Konfiguration und Laufzeit-Fähigkeitsprüfungen. Die genaue Liste hängt vom Ordner config/resources/, den gewährten SMART-Scopes, /metadata, Schreibeinstellungen, Operationseinstellungen und Terminologieeinstellungen ab.

Ressourcen-Tools

Ressourcen-Tools werden aus dem Ordner config/resources/ generiert – eine JSON-Datei pro Ressource (z. B. patient.json), die beim Start gescannt wird. Die mitgelieferte Konfiguration deckt gängige klinische, administrative, Medikations-, Praktiker-, Organisations- und Dokumentressourcen ab. Fügen Sie eine Datei hinzu, um eine Ressource zu ergänzen, oder löschen Sie eine, um sie zu entfernen – keine Quellcodeänderungen erforderlich.

Jedes Ressourcen-Tool unterstützt konfigurierte Suchparameter, optionale direkte Lesevorgänge mit _id, fhirpath und, sofern nicht kompakt gesperrt, responseMode. Direkte Lesevorgänge erfolgen nur, wenn _id das einzige nicht leere Argument ist; _id zusammen mit anderen Parametern bleibt eine Suche, damit die Absicht des Aufrufers nicht stillschweigend verworfen wird.

Ressourcen-Tools sind standardmäßig Suche/Lesen. Setzen Sie FHIR_WRITE_CAPABILITIES, um metadatengesteuerte CRUD-Aktionen zu aktivieren:

FHIR_WRITE_CAPABILITIES=create,update,patch,delete

vread ist verfügbar, wenn die Ressource supportsDirectRead hat und der Server die vread-Interaktion bewirbt. history ist verfügbar, wenn der Server history-instance oder history-type bewirbt. Beide erfordern die SMART-Berechtigung r. Optionale _since- und _at-Parameter filtern Verlaufsergebnisse. Verlaufsantworten sind Bundles und unterstützen kompakten Modus, FHIRPath und Coalescing.

Schreib-Bodies werden vor dem FHIR-Aufruf validiert: body.resourceType muss mit der Tool-Ressource übereinstimmen, body.id muss bei Update mit _id übereinstimmen, falls vorhanden, und Patch erfordert ein JSON-Patch-Array. Scopes werden aus aktivierten Fähigkeiten abgeleitet: Lesen/Suchen verwendet system/Patient.rs, Erstellen/Lesen/Suchen verwendet system/Patient.crs, und vollständige Schreibunterstützung verwendet system/Patient.cruds. SMART v2 hat keinen separaten Patch-Buchstaben, daher wird Patch auf u abgebildet.

Kern-Tools

capabilities gibt die zwischengespeicherte CapabilityStatement-Zusammenfassung, registrierte und übersprungene Tools, Suchparameter, Operationen und Metadatenhinweise zurück.

paginate ruft eine Bundle-Seite mit einer vom Server zurückgegebenen next-URL ab, die gegen den FHIR-Ursprung und erlaubte Pfadpräfixe validiert wird. Wenn der kompakte Modus aktiv ist und die abgerufene Seite weitere Ergebnisse enthält, führt paginate automatisch mehrere Upstream-Seiten zu einer kompakten Antwort zusammen (gleiches Verhalten wie Ressourcen-Suchtools). Übergeben Sie prefetch=false, um Coalescing zu deaktivieren und eine einzelne Seite zu erhalten.

Benannte Operationen

Das operate-Tool ruft FHIR-benannte Operationen aus config/operations.json auf. Der mitgelieferte Operationskatalog deckt klinische Aggregation, Validierung, Dokumentabruf, Terminologieoperationen, IPS-Generierung und Patientenabgleich ab. Sie können den Operationskatalog ohne Quellcodeänderungen erweitern, reduzieren, ersetzen oder deaktivieren.

Terminologie-Tools

Setzen Sie FHIR_TERMINOLOGY_BASE_URL, um zu aktivieren:

Diese Tools rufen den konfigurierten Terminologieserver direkt auf. Sie verwenden nicht die Anmeldedaten des klinischen FHIR-Servers. Verwenden Sie einen Terminologie-Endpunkt, der zu Ihrer ausgewählten FHIR-Version passt, z. B. https://tx.fhir.org/r4.

Bundle-Ausführung

Setzen Sie FHIR_BUNDLE_CAPABILITIES=batch (oder batch,transaction), um bundle zu aktivieren. Dieses Tool übermittelt ein FHIR-Batch- oder Transaktions-Bundle und gibt die Antwort des Servers über die Standard-Antwortpipeline zurück.

Sicherheitsmodell:

• Schreibgeschützte Batch-Bundles (alle GET-Einträge) sind nur mit FHIR_BUNDLE_CAPABILITIES=batch erlaubt.

• Schreibeinträge (POST, PUT, PATCH, DELETE) erfordern zusätzlich FHIR_BUNDLE_WRITES_ENABLED=true und die entsprechende Aktion in FHIR_WRITE_CAPABILITIES.

• Transaktions-Bundles erfordern explizit FHIR_BUNDLE_CAPABILITIES=transaction.

• Jeder Eintrag wird gegen konfigurierte Ressourcen, SMART-Scopes und Metadateninteraktionen vorgeprüft. Wenn ein einzelner Eintrag fehlschlägt, wird das gesamte Bundle vor der Übermittlung abgelehnt.

V1-Ausschlüsse: Bedingte Anfragen, systemweite _history, absolute URLs und $operation-URLs innerhalb von Bundle-Einträgen werden nicht unterstützt.

Verlauf in Bundles: vread (Resource/id/_history/vid), Instanzverlauf (Resource/id/_history) und Typverlauf (Resource/_history)-Einträge sind in Bundles erlaubt, wenn der Server die entsprechende Interaktion bewirbt und Scopes es erlauben. Diese gelten als Lese-Einträge.

Metadaten- und Scope-Gating

Sofern nicht FHIR_METADATA_MODE=off gesetzt ist, ruft fhirHydrant das CapabilityStatement des FHIR-Servers beim Start ab. Im strict-Modus:

• Ressourcen-Tools werden nur registriert, wenn der Ressourcentyp in /metadata vorhanden ist

• Serverseitige Suchsteuerungen wie _count, _sort, _summary, _elements, _include und _revinclude werden nur verfügbar gemacht, wenn sie beworben werden

• Suchparameter werden blockiert, wenn der Server sie nicht bewirbt

• Schreibaktionen erfordern sowohl FHIR_WRITE_CAPABILITIES als auch passende CapabilityStatement-Interaktionen

• Benannte Operationen erfordern, dass der Zielressourcentyp existiert, der gewährte SMART-Scope die Ressource erlaubt und die Operation selbst im CapabilityStatement-Eintrag der Ressource beworben wird

Im warn-Modus werden nicht beworbene Parameter mit einer Warnung erlaubt, aber fehlende Ressourcentypen werden weiterhin übersprungen. SMART-Scopes werden auch zur Laufzeit geprüft, sodass ein Tool im Schema existieren kann und dennoch durch den gewährten Token-Scope blockiert wird.

Token-Ökonomie und Antwortformung

FHIR-Antworten sind oft viel größer, als ein MCP-Client benötigt. fhirHydrant formt Antworten nach dem Abruf für die Token-Ökonomie und nutzt serverseitige Steuerungen, wenn der FHIR-Server sie anbietet.

Kompakte Ausgabe ist KI-orientiertes JSON, nicht kanonisches FHIR. Es entfernt oder vereinfacht FHIR-Rauschen und gängige Datentypen wie meta, Narrative, Erweiterungen, CodeableConcept, Reference, Quantity sowie neuere Datentypen wie CodeableReference. FHIRPath läuft lokal; der FHIR-Server sieht den Ausdruck nie. Wenn die Auswertung fehlschlägt, wird die rohe Antwort zurückgehalten und ein Fehler zurückgegeben.

Strukturierte Antwort-Hülle

Jedes FHIR-Daten-Tool (Ressourcen-Tools, paginate, operate, bundle, system_history) gibt eine einzelne strukturierte Hülle zurück, die über das outputSchema jedes Tools beworben und als structuredContent zurückgegeben wird (der Textinhalt ist dieselbe serialisierte Hülle). Sie enthält die FHIR-Nutzlast (data) sowie Metadaten: Antwortmodus, ein hasMore/continuation-Paginierungssignal, Bundle- und Zusammenführungsstatistiken sowie menschenlesbare notes. Die vollständige Feldliste ist das outputSchema des Tools.

Übergroße Antworten werden nach Möglichkeit aufgeteilt (data bleibt erhalten, abrufbar über continuation); wenn nicht aufteilbar, wird die Hülle mit status: "truncated" markiert und data weggelassen. Die Kürzung ist ein erfolgreiches, aber teilweises Ergebnis, kein Fehler. Die Fähigkeiten- und Terminologie-Tools geben ihre eigenen strukturierten Formen zurück, nicht diese FHIR-Hülle.

Seiten-Zusammenführung

Wenn der Kompaktmodus für eine Suche aktiv ist (Ressourcen-Tools oder paginate), ruft der Server mehrere vorgelagerte FHIR-Seiten sequenziell ab, kompaktiert jede Seite sofort und gibt ein konsolidiertes kompaktes Bundle zurück. Dies reduziert die MCP-Roundtrips von vielen „nächste Seite“-Aufrufen auf einen einzigen.

• maxResults setzt ein Ziel – der Server stoppt das Abrufen, sobald dieser Schwellenwert überschritten ist (kann leicht überschreiten, da ganze Seiten angehängt werden)

• prefetch=false deaktiviert die Zusammenführung für einen Aufruf

• _count steuert weiterhin die vorgelagerte FHIR-Seitengröße

• Die Zusammenführung stoppt bei konfigurierbaren Seiten-, Eintrags-, Byte- und Zeitlimits

• continuation.url zeigt auf die Stelle, an der der Server gestoppt hat; rufen Sie paginate mit responseMode=compact auf, um fortzufahren (hasMore zeigt an, dass weitere vorhanden sind)

• FHIRPath-gefilterte Anfragen bleiben einseitig (keine Zusammenführung)

• responseMode=full gibt immer eine einzelne vorgelagerte Seite zurück

Audit-Ereignisse

Setzen Sie FHIR_AUDIT_SINK auf eine beliebige Kombination aus console, file und http.

Die http-Senke sendet jedes Audit-Ereignis per POST an einen externen Collector, SIEM oder ein FHIR-Audit-Repository (nicht an den FHIR-Server selbst). Setzen Sie FHIR_AUDIT_HTTP_URL auf das Ziel und FHIR_AUDIT_HTTP_FORMAT entweder auf raw (das interne PHI-leichte Audit-JSON, für generische Collector wie Splunk HEC oder Datadog) oder auf fhir-auditevent (eine minimale FHIR-R4-AuditEvent-Ressource, geeignet für ATNA-artige und FHIR-native Audit-Repositories). Das fhir-auditevent-Mapping ist bewusst leichtgewichtig – es ist kein vollständiges ATNA/BALP-Konformitätsprofil. Ein optionaler FHIR_AUDIT_HTTP_AUTH-Wert wird unverändert als Authorization-Header gesendet. Die Zustellung erfolgt fire-and-forget mit einem 5s-Timeout; Transportfehler werden protokolliert und beeinflussen niemals Tool-Antworten.

Audit-Ereignisse umfassen Zeitstempel, Tool, Ressourcentyp (falls zutreffend), Operation, Status, Dauer, Antwortgröße, Paginierungszusammenfassung, Anforderungs-ID und optional den proxy-authentifizierten Benutzer. Sie enthalten standardmäßig keinen FHIR-Ressourceninhalt.

Wenn Sie hinter einem authentifizierenden Proxy laufen, setzen Sie FHIR_AUDIT_USER_HEADER auf den vertrauenswürdigen Identitäts-Header, der von diesem Proxy eingefügt wird:

Gängige Header: Azure EasyAuth X-MS-CLIENT-PRINCIPAL-NAME, OAuth2 Proxy X-Auth-Request-Email, Cloudflare Access Cf-Access-Authenticated-User-Email.

Verwenden Sie dies nur, wenn der Proxy eingehende Kopien dieses Headers entfernt oder überschreibt. Andernfalls können Clients beliebige Audit-Benutzer vortäuschen.

SMART-Backend-Authentifizierung und -Schlüssel

fhirHydrant verwendet SMART Backend Services: Client-Anmeldedaten plus eine signierte JWT-Assertion. Dies ist ein Backend-FHIR-Zugriff, kein browserbasierter SMART-Standalone-Start; es gibt keinen interaktiven Redirect-/Login-Flow im MCP-Pfad.

FHIR_ACTIVE_KEY enthält den rohen PKCS#8-Signaturschlüssel (RSA, signiert mit RS384, oder EC P-384, signiert mit ES384). Im HTTP-Modus stellt der eingebaute /jwks-Endpunkt öffentliche Schlüssel für den aktiven Schlüssel sowie alle zurückgezogenen Schlüssel bereit, wenn FHIR_JWKS_URL nicht gesetzt ist. Der kid für jeden Schlüssel wird automatisch über einen gekürzten RFC-7638-JWK-Thumbprint abgeleitet (erste 12 Base64url-Zeichen des SHA-256 über die kanonischen öffentlichen JWK-Mitglieder) und beim Start protokolliert.

Workflow zur Schlüsselrotation:

1. Generieren Sie einen neuen Schlüssel (RSA-2048 oder EC P-384).

2. Fügen Sie das neue PEM zu FHIR_RETIRED_KEYS hinzu und stellen Sie erneut bereit, sodass JWKS beide enthält.

3. Registrieren Sie den neuen kid (beim Start protokolliert) bei Ihrem Auth-Server.

4. Verschieben Sie das neue PEM zu FHIR_ACTIVE_KEY und das alte PEM zu FHIR_RETIRED_KEYS. Stellen Sie erneut bereit.

5. Nach Ablauf der Auth-Server-Caches entfernen Sie den alten Schlüssel aus FHIR_RETIRED_KEYS.

Wenn Sie externes JWKS verwenden, veröffentlichen Sie den neuen öffentlichen Schlüssel, bevor Sie FHIR_ACTIVE_KEY wechseln.

Umgebungsvariablen

Siehe .env.example für ein vollständiges Beispiel.

Erforderlich

Optional

Explizite FHIR_SERVER_URL- und FHIR_TOKEN_URL-Werte haben immer Vorrang vor abgeleiteten URLs.

FHIR-Versionsunterstützung

Setzen Sie FHIR_VERSION, um das aktive R4+-FHIR-Release auszuwählen. Es steuert die abgeleitete FHIR-API-URL, den FHIRPath-Modellkontext und die Metadaten des kompakten Antwortmodells. Einige Releases verwenden möglicherweise das nächstgelegene kompatible FHIRPath-Modell. Für Terminologie verwenden Sie einen Endpunkt, der zum ausgewählten FHIR-Release passt. Startprotokolle weisen darauf hin, wenn explizite FHIR- oder Terminologie-URLs offenbar auf eine andere Version verweisen.

Anpassen von Tools und Nachrichten

Alles unter config/ ist ohne Quellcode-Änderungen anpassbar.

Die Konfiguration wird als partielles Overlay aufgelöst: Für jede Datei überschreibt eine ./config/<file> im aktuellen Arbeitsverzeichnis (sofern vorhanden) den mitgelieferten Standard, und alles, was Sie auslassen, fällt auf den eingebauten Standard zurück. So funktionieren npm-Installationen ohne weitere Einrichtung, und zum Anpassen legen Sie einen ./config-Ordner neben dem Ort ab, an dem Sie den Server starten, der nur die Dateien enthält, die Sie ändern möchten.

Es gibt zwei Overlay-Granularitäten:

• Ganze Datei (resources/*.json, operations.json, search-controls.json, core-tools.json, instructions/*): Eine von Ihnen bereitgestellte Datei ersetzt die mitgelieferte Datei vollständig. Eine neue Ressourcendatei (z. B. ./config/resources/myresource.json) fügt ein Tool hinzu. Das Overlay kann überschreiben und hinzufügen, aber keine mitgelieferte Ressource entfernen – um einen strikt minimalen Katalog auszuliefern, entfernen Sie die mitgelieferten Dateien unter config/resources/ (siehe das Compose-Beispiel).

• Pro Schlüssel (messages/*.json): Eine lokale Datei überschreibt nur die einzelnen Schlüssel, die sie enthält; jeder andere Schlüssel fällt auf den mitgelieferten Standard zurück. So können Sie eine einzelne Beschreibung oder Nachricht neu justieren, ohne die gesamte Datei zu kopieren. Unbekannte Schlüssel, leere Werte und fehlerhaftes JSON schlagen beim Start sofort fehl, um Tippfehler zu erkennen.

messages/*.json-Dateien werden beim Prozessstart einmal gelesen. Um sie zu ändern, ist ein Serverneustart erforderlich (und bei Tool-Schemas oder Anweisungen eine erneute Client-Verbindung), damit die Änderungen wirksam werden. Das Entwicklungs-Hot-Reload für Ressourcen, Suchsteuerungen und Operationen wird unten beschrieben.

Ressourcendefinitionsschema

Jede Datei in config/resources/ ist ein einzelnes Ressourcendefinitionsobjekt. Dateien werden in Dateinamensreihenfolge gescannt; der Dateiname ist üblicherweise der Ressourcenname in Kleinbuchstaben (z. B. patient.json). Jedes Objekt hat die folgenden Felder:

searchParams-Werte sind Beschreibungen und kein vollständiges FHIR-Fähigkeitsmodell. Serverspezifisches Suchverhalten kann weiterhin gelten.

Hot Reload

In der Entwicklung (NODE_ENV ist nicht production) werden der Ordner config/resources/, search-controls.json und operations.json überwacht. Ungültiges JSON behält den letzten gültigen Snapshot. Ein inhaltlich verändertes Neuladen wird transaktional angewendet: Wenn sich die abgeleiteten SMART-Scopes ändern, wird ein Ersatztoken erworben, bevor die neuen Definitionen und Tool-Registrierungen übernommen werden, sodass ein fehlgeschlagener Erwerb den laufenden Katalog unberührt lässt. Das Hinzufügen/Entfernen von Tools sowie Schemaänderungen bei Operationen und Parameternamen werden live neu registriert – kein Neustart erforderlich. Semantisch unveränderte Speicherungen lösen kein Aktualisieren aus. Die Produktion liest die Konfiguration einmal beim Start, aber eine Laufzeitänderung von /metadata (über capabilities(refresh=true)) oder eine Änderung der Backend-SMART-Scopes bei der Token-Aktualisierung wertet die verfügbaren Tools in jedem Modus neu aus.

Eine Grenze ist unvermeidbar: Die Tool-Liste und Schemas aktualisieren sich per Hot Refresh, aber die Server-instructions werden einmalig während der MCP-initialize gesendet und können bei einer bestehenden Verbindung nicht ersetzt werden. Ein Client muss sich erneut verbinden/neu initialisieren, um geänderten Anweisungstext zu erhalten.

Transports

Stdio

Setzen Sie MCP_TRANSPORT=stdio. stdout ist für das MCP-Protokoll reserviert; Logs werden nach stderr umgeleitet. Verwenden Sie für Stdio-Bereitstellungen eine externe FHIR_JWKS_URL.

Streamable HTTP

Der HTTP-Transport ist zustandslos und stellt MCP bereit unter:

POST http://localhost:5000/mcp
Accept: application/json, text/event-stream
Content-Type: application/json

MCP-Client-Konfiguration:

{
   "mcpServers": {
      "fhirhydrant": {
         "url": "http://localhost:5000/mcp"
      }
   }
}

GET /health gibt einen PHI-freien Bereitschaftssnapshot zurück:

{
   "status": "ok",
   "mcp": true,
   "metadata": true,
   "tools": 23,
   "auth": true,
   "tokenExpiresIn": 287
}

Wenn Autorisierung aktiviert ist, meldet authz den aktiven Anbieter, und tools wird weggelassen, da die Anzahl der registrierten Tools aufruferspezifisch ist.

Verwenden Sie einen Reverse-Proxy für TLS und Benutzerauthentifizierung, wenn Sie HTTP über localhost hinaus bereitstellen. Setzen Sie ALLOWED_HOSTS, wenn Sie an eine öffentliche Schnittstelle binden.

Pro-Aufrufer-Autorisierung (Entra, optional)

Standardmäßig (MCP_AUTHZ=none) sieht jeder Aufrufer den vollständigen Tool-Satz, der nur durch /metadata und die Backend-SMART-Scopes eingeschränkt ist. Das Setzen von MCP_AUTHZ=entra fügt eine optionale Ebene pro Aufrufer hinzu: Jede /mcp-Anfrage muss ein von Microsoft Entra ausgestelltes Authorization: Bearer <token> enthalten, und die App-Rollen des Aufrufers bestimmen, welche Tools für diese Anfrage erstellt werden. Dies ist nur eine Autorisierung auf MCP-Ebene – sie ersetzt niemals die eigene Autorisierung des FHIR-Servers und kann die vom Backend-SMART-Token und der Konfiguration bereits erlaubten Berechtigungen nur einschränken.

Die API-App-Registrierung muss in ihrem Manifest requestedAccessTokenVersion auf 2 setzen. Der Anbieter validiert mandantenspezifische v2-Aussteller und erwartet, dass MCP_ENTRA_AUDIENCE die Client-ID der API-Anwendung ist.

Tools, für die einem Aufrufer eine Rolle fehlt, werden überhaupt nicht registriert – sie fehlen in tools/list und werden nicht nur blockiert. Hilfstools (capabilities, paginate, terminology_lookup, code_search) sind nie durch Rollen eingeschränkt.

App-Rollenwerte (mit dem Standardpräfix FhirHydrant):

Erfordert HTTP-Transport; MCP_AUTHZ=entra mit MCP_TRANSPORT=stdio schlägt beim Start fehl. Fehlende oder ungültige Bearer-Tokens erhalten 401.

Hinzufügen eines Autorisierungsanbieters

Entra ist der einzige mitgelieferte Anbieter, aber die Autorisierungsebene ist anbieterneutral. Dies ist eine Quellcode-Erweiterung, kein Laufzeit-Plugin: Das npm-Paket enthält nur bin/server.js (Anbieter sind darin gebündelt). Einen Anbieter hinzuzufügen bedeutet daher, das Repository zu forken oder zu klonen und neu zu bauen.

Die gemeinsame Pipeline ist providerunabhängig – ein Provider bildet lediglich einen Authorization-Header auf { subject, roles } ab. Das Rollenvokabular (.Read/.Write/Operation.<key>/Bundle/SystemHistory.Read/Admin) und die MCP_ROLE_PREFIX-Behandlung werden von decideAuthz für jeden Provider angewendet.

Um einen hinzuzufügen (z. B. auth0), sind nur zwei Änderungen nötig:

1. Erstellen Sie ts/mcp/authz/auth0.ts, das einen AuthzProvider exportiert – implementieren Sie validate(authorization), um { subject, roles } zurückzugeben (werfen Sie einen Fehler, um abzulehnen), und optional validateConfig(), um bei fehlenden Provider-Umgebungsvariablen frühzeitig zu scheitern. Behalten Sie alle providerspezifischen Umgebungsvariablen in diesem Modul; fügen Sie keine Felder zu Config hinzu.

2. Fügen Sie einen Eintrag zu ts/mcp/authz/registry.ts hinzu: auth0: () => import("./auth0.ts").then((m) => m.auth0Provider).

Das ist alles. Der AuthzMode-Typ, der MCP_AUTHZ-Parser und seine Fehlermeldung werden automatisch aus den Registry-Schlüsseln abgeleitet, sodass MCP_AUTHZ=auth0 einfach mit voller Typsicherheit funktioniert – keine andere Datei muss geändert werden.

Bereitstellungsbeispiele

Das Verzeichnis examples/ enthält eigenständige Bereitstellungsbeispiele für Docker Compose, Reverse-Proxy (Caddy), Azure Container Apps, Azure App Service und Kubernetes. Jedes enthält ein Dockerfile, das die Installation aus npm vornimmt, sowie ein config/-Overlay, das zeigt, wie verschiedene Konfigurationsdateien überschrieben werden.

Entwicklung

# dev server
npm run dev

# type-check
npm run check

# build and run
npm run build
npm start

Die Build-Ausgabe wird nach bin/server.js geschrieben.