Skip to main content
Glama

fhirHydrant: FHIR MCP サーバー

R4+ FHIR API 向けの、現代的で完全に設定可能なオープンソースの Node.js MCP サーバーです。 SMART on FHIR v2 Backend Services で署名付き JWT クライアント認証情報を使用して、MCP 互換クライアントを臨床データに接続します。

fhirHydrant は、FHIR リソース、名前付きオペレーション、用語検索、ページネーションを MCP ツールに変換します。デフォルトのリソースとオペレーションは出発点です。リソース、オペレーション、検索コントロール、指示、メッセージは、ソースを変更することなく設定ファイルで拡張、削減、置換できます。

  • JWKS ホスティング、キーローテーション、トークンリフレッシュ、動的スコープを備えた SMART Backend Services 認証

  • 検索、直接読み取り、vread、履歴、およびオプションのメタデータゲート付き CRUD のための設定可能なリソースツール

  • 臨床データ、用語、IPS、患者マッチング、検証、カスタムワークフローのための設定駆動型の名前付きオペレーション

  • CapabilityStatement 対応ツール、検索コントロール、オペレーションゲーティング、ランタイムスコープチェック

  • トークン経済機能: コンパクトなレスポンス、FHIRPath フィルタリング、バイト制限、_count 整形、過大な Bundle の再試行

  • オプションの用語ツール、PHI ライト監査イベント(デフォルトではリソースコンテンツなし)、stdio または Streamable HTTP トランスポート

注: MCP ツール呼び出しを通じて返される FHIR データには PHI が含まれる場合があります。 MCP クライアントのトランスクリプト保存とロギング動作が、コンプライアンス要件に一致していることを確認してください。

目次

Related MCP server: smart-mcp-server

クイックスタート

要件

  • Node.js >= 24

  • サポートされている FHIR サーバー

  • SMART 認証(デフォルト)の場合: SMART Backend Services クライアント登録と、公開鍵が JWKS で利用可能な RSA-2048 または EC P-384 秘密鍵

公開された認証なしの FHIR テストサーバーに対して実行するには、FHIR_AUTH=none を設定し、クライアントとキーを完全にスキップします(認証なしアクセス を参照)。

stdio トランスポートは通常、外部でホストされた JWKS URL を必要とします。組み込みの /jwks エンドポイントは、fhirHydrant が HTTP 上で SMART 認証を使用して実行されている場合にのみ利用可能です。

インストール

# install globally
npm install -g fhirhydrant

# or run without installing
npx fhirhydrant

ソースから実行:

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

MCP クライアント設定

デスクトップ MCP クライアントの場合、stdio が通常最も簡単なトランスポートです:

{
   "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 は、PKCS#8 秘密鍵(RSA または EC P-384)を base64 エンコードしたものです。 kid は起動時に切り詰められた JWK サムプリントから自動的に導出され、コンソールにログ出力されます。

認証なしアクセス

fhirHydrant を公開された認証なしの FHIR エンドポイントに向けるには(オープンサンドボックスでのテストに便利)、FHIR_AUTH=none を設定します。クライアント ID や署名キーは不要で、トークンは要求されず、リクエストは Authorization ヘッダーなしで送信されます:

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

ツール

fhirHydrant は、設定とランタイム機能チェックからツールを登録します。正確なリストは、config/resources/ フォルダ、付与された SMART スコープ、/metadata、書き込み設定、オペレーション設定、用語設定によって異なります。

ツールまたはファミリー

利用可能な場合

目的

リソースツール

リソースが設定され、メタデータ/スコープで許可されている場合

FHIR リソースの検索、直接読み取り、vread、履歴、およびオプションで CRUD

system_history

サーバーがシステムレベルの history インタラクションを宣伝し、スコープが許可する場合

すべてのリソースタイプにわたるシステムレベルの変更履歴を取得

capabilities

常に登録

CapabilityStatement の概要、登録済みツール、スキップされたツール、検索パラメータ、オペレーション、メタデータノートを検査

paginate

常に登録

サーバーが返した next URL を使用して FHIR Bundle の次のページを取得

operate

少なくとも 1 つの名前付きオペレーションがゲーティングを通過する場合

臨床データ、用語、IPS、マッチング、検証、またはカスタムワークフローのための設定済み FHIR 名前付きオペレーションを呼び出す

bundle

FHIR_BUNDLE_CAPABILITIES が設定されている場合

FHIR バッチまたはトランザクション Bundle を送信; 書き込みには追加のオプトインが必要

terminology_lookup

FHIR_TERMINOLOGY_BASE_URL が設定されている場合

1 つの LOINC または SNOMED CT コードを検索

code_search

FHIR_TERMINOLOGY_BASE_URL が設定されている場合

テキストで LOINC または SNOMED CT コードを検索

リソースツール

リソースツールは config/resources/ フォルダから生成されます。リソースごとに 1 つの JSON ファイル(例: patient.json)があり、起動時にスキャンされます。同梱の設定は、一般的な臨床、管理、投薬、開業医、組織、文書リソースをカバーしています。ファイルを追加してリソースを追加するか、削除してリソースを削除します。ソースの変更は不要です。

各リソースツールは、設定された検索パラメータ、オプションの直接読み取り(_id を使用)、fhirpath、およびコンパクトロックされていない限り responseMode をサポートします。直接読み取りは、_id が唯一の空でない引数である場合にのみ行われます。_id と他のパラメータが一緒の場合は検索のままなので、呼び出し元の意図が静かに破棄されることはありません。

リソースツールはデフォルトで検索/読み取りです。FHIR_WRITE_CAPABILITIES を設定して、メタデータゲート付き CRUD アクションを有効にします:

FHIR_WRITE_CAPABILITIES=create,update,patch,delete

アクション

必須パラメータ

FHIR 呼び出し

vread

_id, _vid

GET /ResourceType/{id}/_history/{vid}

history

_id(インスタンス)またはなし(タイプ)

GET /ResourceType/{id}/_history または GET /ResourceType/_history

create

body

POST /ResourceType

update

_id, body

PUT /ResourceType/{id}

patch

_id, body

PATCH /ResourceType/{id}(JSON Patch を使用)

delete

_id

DELETE /ResourceType/{id}

vread は、リソースが supportsDirectRead を持ち、サーバーが vread インタラクションを宣伝している場合に利用可能です。history は、サーバーが history-instance または history-type を宣伝している場合に利用可能です。どちらも SMART r 権限が必要です。オプションの _since および _at パラメータは履歴結果をフィルタリングします。履歴レスポンスは Bundle であり、コンパクトモード、FHIRPath、および合体をサポートします。

書き込みボディは FHIR 呼び出しの前に検証されます: body.resourceType はツールのリソースと一致する必要があり、body.id は更新時に存在する場合は _id と一致する必要があり、パッチには JSON Patch 配列が必要です。スコープは有効な機能から導出されます: 読み取り/検索は system/Patient.rs、作成/読み取り/検索は system/Patient.crs、完全な書き込みサポートは system/Patient.cruds を使用します。SMART v2 には別のパッチ文字がないため、パッチは u にマップされます。

コアツール

capabilities は、キャッシュされた CapabilityStatement の概要、登録済みおよびスキップされたツール、検索パラメータ、オペレーション、メタデータノートを返します。

paginate は、FHIR オリジンと許可されたパスプレフィックスに対して検証されたサーバー返却の next URL を使用して、1 つの Bundle ページを取得します。コンパクトモードがアクティブで、取得したページにさらに結果がある場合、paginate は複数のアップストリームページを 1 つのコンパクトレスポンスに自動的に合体します(リソース検索ツールと同じ動作)。prefetch=false を渡すと合体を無効にし、単一ページを取得します。

名前付きオペレーション

operate ツールは、config/operations.json から FHIR 名前付きオペレーションを呼び出します。同梱のオペレーションカタログは、臨床集計、検証、文書検索、用語オペレーション、IPS 生成、患者マッチングをカバーしています。ソースを変更せずに、オペレーションカタログを拡張、削減、置換、または無効にできます。

用語ツール

FHIR_TERMINOLOGY_BASE_URL を設定して有効にします:

ツール

説明

terminology_lookup

1 つの LOINC または SNOMED CT コードを検索

code_search

ページングサポート付きのテキストフィルターでコードを検索

これらのツールは、設定された用語サーバーを直接呼び出します。臨床 FHIR サーバーの認証情報は使用しません。選択した FHIR リリースに一致する用語エンドポイントを使用してください。例: https://tx.fhir.org/r4

Bundle 実行

FHIR_BUNDLE_CAPABILITIES=batch(または batch,transaction)を設定して bundle を有効にします。このツールは FHIR バッチまたはトランザクション Bundle を送信し、サーバーのレスポンスを標準のレスポンスパイプラインを通じて返します。

安全モデル:

  • 読み取り専用バッチ Bundle(すべて GET エントリ)は、FHIR_BUNDLE_CAPABILITIES=batch だけで許可されます。

  • 書き込みエントリ(POST、PUT、PATCH、DELETE)には、追加で FHIR_BUNDLE_WRITES_ENABLED=trueFHIR_WRITE_CAPABILITIES 内の対応するアクションが必要です。

  • トランザクション Bundle には、明示的な FHIR_BUNDLE_CAPABILITIES=transaction が必要です。

  • すべてのエントリは、設定されたリソース、SMART スコープ、メタデータインタラクションに対して事前チェックされます。単一のエントリが失敗した場合、Bundle 全体が送信前に拒否されます。

V1 の除外: 条件付きリクエスト、システムレベルの _history、絶対 URL、Bundle エントリ内の $operation URL はサポートされていません。

Bundle 内の履歴: vreadResource/id/_history/vid)、インスタンス履歴(Resource/id/_history)、タイプ履歴(Resource/_history)エントリは、サーバーが対応するインタラクションを宣伝し、スコープが許可する場合に Bundle 内で許可されます。これらは読み取りエントリとしてカウントされます。

メタデータとスコープゲーティング

FHIR_METADATA_MODE=off でない限り、fhirHydrant は起動時に FHIR サーバーの CapabilityStatement を取得します。strict モードでは:

  • リソースツールは、リソースタイプが /metadata に存在する場合にのみ登録されます

  • _count_sort_summary_elements_include_revinclude などのサーバー側検索コントロールは、宣伝されている場合にのみ公開されます

  • 検索パラメータは、サーバーが宣伝していない場合にブロックされます

  • 書き込みアクションには、FHIR_WRITE_CAPABILITIES と一致する CapabilityStatement インタラクションの両方が必要です

  • 名前付きオペレーションには、ターゲットリソースタイプが存在し、付与された SMART スコープがリソースを許可し、オペレーション自体がリソースの CapabilityStatement エントリで宣伝されている必要があります

warn モードでは、宣伝されていないパラメータは警告付きで許可されますが、存在しないリソースタイプはスキップされます。SMART スコープもランタイムでチェックされるため、ツールがスキーマに存在しても、付与されたトークンスコープによってブロックされる可能性があります。

トークン経済とレスポンス整形

FHIRレスポンスは、多くの場合MCPクライアントが必要とするよりもはるかに大きくなります。fhirHydrantは、取得後にトークン消費を抑えるようレスポンスを整形し、FHIRサーバーがサーバー側の制御を提供している場合はそれを利用します。

機能

動作

_countのデフォルト/上限

デフォルトでは_countは注入されません(ページサイズはサーバーが決定)。FHIR_DEFAULT_COUNTを設定すると注入されます。FHIR_MAX_COUNTは呼び出し側の明示的な値を上限で制限します(0 = 上限なし)

ページ結合

コンパクトモードが有効な場合、サーバーは複数の上流ページを順次取得し、各ページを即座に圧縮して、1つの統合されたBundleを返します。maxResultsprefetchFHIR_PREFETCH_*環境変数によって制御されます

バイト制限

FHIR_MAX_RESPONSE_BYTESは、モデル向けのすべてのJSONレスポンスを制限します。サイズ超過のBundleは透過的にチャンク分割されます

自動リトライ

サイズ超過の検索Bundleは、まずローカルでのチャンク分割を試み、次にフォールバックとしてより小さい_countでリトライします

FHIRPath

fhirpathは返されたFHIR JSONをローカルでフィルタリングし、一致するノードを配列として返します

コンパクトモード

responseMode=compactは、一般的なFHIRエンベロープのノイズを取り除き、データ型を簡素化します

フルモード

responseMode=fullは生のFHIR JSONを返します

ロックされたコンパクト

FHIR_RESPONSE_MODE=compact-lockedは、ツールスキーマからresponseModeを隠します

ネイティブアーティファクト

非JSONレスポンス(ドキュメント、画像、DICOM、RTF、HTML、XML、CSV、NDJSON、ZIP、octet-stream)およびJSON FHIR Binaryは、メタデータエンベロープと1つのMCP埋め込みテキスト/BLOBリソースに正規化されます。FHIR_MAX_ARTIFACT_MB(JSON制限ではなく)によって上限が設定され、チャンク分割されることはなく、FHIRPath/圧縮/結合も適用されません。JSON専用の整形引数は注記付きで無視されます

コンパクト出力は、AI向けのJSONであり、標準的なFHIRではありません。meta、ナラティブ、拡張、CodeableConceptReferenceQuantityなどのFHIRノイズや一般的なデータ型、およびCodeableReferenceなどの新しいデータ型を削除または簡素化します。

FHIRPathはローカルで実行されるため、FHIRサーバーが式を見ることはありません。評価に失敗した場合、生のレスポンスは返されず、エラーが返されます。

構造化レスポンスエンベロープ

すべてのFHIRデータツール(リソースツール、paginateoperatebundlesystem_history)は、単一の構造化エンベロープを返します。これは各ツールのoutputSchemaで公開され、structuredContentとして返されます(テキストコンテンツは同じエンベロープをシリアライズしたものです)。このエンベロープには、FHIRペイロード(data)に加えて、レスポンスモード、hasMore/continuationページネーションシグナル、Bundleと結合の統計、人間が読めるnotesというメタデータが含まれます。完全なフィールドリストはツールのoutputSchemaです。

サイズ超過のレスポンスは、可能な場合はチャンク分割されます(dataは保持され、continuation経由で取得可能)。チャンク分割できない場合は、エンベロープにstatus: "truncated"がマークされ、dataは省略されます。トランケーションは成功したが部分的な結果であり、エラーではありません。capabilitiesツールとterminologyツールは、このFHIRエンベロープではなく、独自の構造化シェイプを返します。

ページ結合

検索(リソースツールまたはpaginate)でコンパクトモードが有効な場合、サーバーは複数の上流FHIRページを順次取得し、各ページを即座に圧縮して、1つの統合されたコンパクトBundleを返します。これにより、MCPのラウンドトリップは、多数の「次のページ」呼び出しから1回に削減されます。

  • maxResultsは目標を設定します。サーバーはこのしきい値を超えるとフェッチを停止します(ページ全体が追加されるため、わずかに超過する場合があります)。

  • prefetch=falseは、1回の呼び出しで結合を無効にします。

  • _countは引き続き上流のFHIRページサイズを制御します。

  • 結合は、設定可能なページ数、エントリ数、バイト数、および時間の制限で停止します。

  • continuation.urlは、サーバーが停止した場所を指します。続行するにはresponseMode=compactを指定してpaginateを呼び出します(hasMoreはさらに残りがあることを示します)。

  • FHIRPathでフィルタリングされたリクエストは単一ページのままです(結合なし)。

  • responseMode=fullは常に単一の上流ページを返します。

監査イベント

FHIR_AUDIT_SINKは、consolefilehttpの任意の組み合わせに設定します。

httpシンクは、各監査イベントを外部コレクター、SIEM、またはFHIR監査リポジトリ(FHIRサーバー自体ではありません)にPOSTします。FHIR_AUDIT_HTTP_URLに宛先を設定し、FHIR_AUDIT_HTTP_FORMATにはraw(Splunk HECやDatadogなどの汎用コレクター向けの内部PHIライト監査JSON)またはfhir-auditevent(ATNAスタイルおよびFHIRネイティブの監査リポジトリに適した最小限のFHIR R4 AuditEventリソース)のいずれかを設定します。fhir-auditeventマッピングは意図的に軽量です。完全なATNA/BALP準拠プロファイルではありません。オプションのFHIR_AUDIT_HTTP_AUTH値は、Authorizationヘッダーとしてそのまま送信されます。配信はファイアアンドフォーゲット方式で、5秒のタイムアウトが設定されます。トランスポートの失敗はログに記録され、ツールのレスポンスには一切影響しません。

監査イベントには、タイムスタンプ、ツール、該当する場合はリソースタイプ、操作、ステータス、所要時間、レスポンスサイズ、ページネーションの要約、リクエストID、およびオプションのプロキシ認証済みユーザーが含まれます。デフォルトではFHIRリソースのコンテンツは含まれません。

認証プロキシの背後で実行する場合は、FHIR_AUDIT_USER_HEADERを、そのプロキシによって注入される信頼されたIDヘッダーに設定します。

一般的なヘッダー: Azure EasyAuth X-MS-CLIENT-PRINCIPAL-NAME、OAuth2 Proxy X-Auth-Request-Email、Cloudflare Access Cf-Access-Authenticated-User-Email

この設定は、プロキシがそのヘッダーのインバウンドコピーを削除または上書きする場合にのみ使用してください。それ以外の場合、クライアントは任意の監査ユーザーを偽装できます。

SMARTバックエンド認証とキー

fhirHydrantはSMART Backend Services(クライアント認証情報と署名付きJWTアサーション)を使用します。これはブラウザベースのSMARTスタンドアロン起動ではなく、バックエンドのFHIRアクセスです。MCPパスに対話型のリダイレクト/ログインフローはありません。

FHIR_ACTIVE_KEYは、生のPKCS#8署名キー(RSA、RS384署名、またはEC P-384、ES384署名)を保持します。HTTPモードでは、FHIR_JWKS_URLが設定されていない場合、組み込みの/jwksエンドポイントが、アクティブキーと退役キーの公開キーを公開します。各キーのkidは、切り詰められたRFC 7638 JWKサムプリント(正規の公開JWKメンバーに対するSHA-256の最初の12 base64url文字)から自動的に導出され、起動時にログに記録されます。

キーローテーションのワークフロー:

  1. 新しいキー(RSA-2048またはEC P-384)を生成します。

  2. 新しいPEMをFHIR_RETIRED_KEYSに追加して再デプロイし、JWKSに両方が含まれるようにします。

  3. 新しいkid(起動時にログに記録されます)を認証サーバーに登録します。

  4. 新しいPEMをFHIR_ACTIVE_KEYに移動し、古いPEMを FHIR_RETIRED_KEYSに移動します。再デプロイします。

  5. 認証サーバーのキャッシュが期限切れになったら、FHIR_RETIRED_KEYSから古いキーを削除します。

外部JWKSを使用する場合は、FHIR_ACTIVE_KEYを切り替える前に新しい公開キーを公開してください。

環境変数

完全なサンプルについては、.env.exampleを参照してください。

必須

変数

説明

FHIR_BASE_URL

FHIRサーバーのURLとトークンURLを導出するために使用されるベースURL。FHIR_SERVER_URLが設定されている場合はオプション(SMART認証の場合はFHIR_TOKEN_URLも)

FHIR_CLIENT_ID

SMART Backend ServicesのクライアントID(FHIR_AUTH=noneの場合は不要)

FHIR_ACTIVE_KEY

Base64エンコードされたPKCS#8 PEM署名キー(RSAまたはEC P-384)。(FHIR_AUTH=noneの場合は不要)

オプション

変数

デフォルト

説明

FHIR_AUTH

smart

smart(SMART Backend Services)または none(認証なし、公開テストエンドポイント用)

FHIR_RETIRED_KEYS

未設定

JWKSローテーション用のカンマ区切りのbase64エンコードされたPEM

FHIR_VERSION

R4

アクティブなR4+ FHIRリリース。派生URL、FHIRPathモデル、コンパクトモデルのメタデータを制御します。

FHIR_SERVER_URL

<base>/api/FHIR/<FHIR_VERSION>

明示的なFHIR API URLの上書き

FHIR_TOKEN_URL

<base>/oauth2/token

明示的なトークンエンドポイントの上書き

FHIR_JWKS_URL

未設定

外部JWKS URL。HTTPモードでは省略すると組み込みの/jwksが有効になります。

MCP_TRANSPORT

http

http または stdio

PORT

5000

HTTPリスナーポート

BIND_HOST

0.0.0.0 (or 127.0.0.1 with --dev flag)

HTTPバインドアドレス

ALLOWED_HOSTS

未設定

DNSリバインディング保護用のカンマ区切りのホスト名

FHIR_METADATA_MODE

strict

/metadata検証用のstrictwarn、またはoff

FHIR_DEFAULT_COUNT

0

許可された場合に検索に注入されるデフォルトの_count。0 = サーバーが決定

FHIR_MAX_COUNT

0

明示的な呼び出し元の_count値の上限。0 = 上限なし

FHIR_MAX_RESPONSE_BYTES

262144

モデル向けJSONレスポンスのバイト制限。サイズ超過のBundleはチャンク化されます。

FHIR_MAX_ARTIFACT_MB

16

ネイティブ/バイナリアーティファクト本文用の個別のバイト上限(MiB)。JSON制限とは独立(base64転送で約+33%)

FHIR_REQUEST_TIMEOUT_MS

30000

送信FHIRリクエストの試行ごとのタイムアウト

MCP_JSON_LIMIT

4mb

受け入れ可能なMCPリクエスト本文の最大サイズ(Express json limit文字列)。大きな書き込み/バンドルペイロードが拒否される場合は引き上げてください。

MCP_AUTHZ

none

認可プロバイダー: none または entra。呼び出し元ごとにツールを制限します(HTTP + Authorization: Bearer のみ)

MCP_ROLE_PREFIX

FhirHydrant

付与されたロール値のプレフィックス(例: FhirHydrant.Patient.Read

MCP_ENTRA_TENANT_ID

未設定

EntraテナントGUID(ドメインエイリアスではありません)。MCP_AUTHZ=entra のときに必須

MCP_ENTRA_AUDIENCE

未設定

v2アクセストークンのaudに期待されるAPIアプリケーション(クライアント)ID。MCP_AUTHZ=entra のときに必須

FHIR_RESPONSE_MODE

未設定

compactfull、またはcompact-locked。未設定の場合、検索はデフォルトでcompact、直接読み取りはデフォルトでfull

FHIR_WRITE_CAPABILITIES

未設定

カンマ区切りの書き込みアクション: createupdatepatchdelete

FHIR_VALIDATE_WRITES

local

offlocal(クライアント側の構造チェック)、またはserver(create/updateのためのローカル+サーバー$validate事前チェック)

FHIR_WRITE_DRY_RUN

false

FHIRサーバーに対して実行せずに書き込みを検証してログに記録するにはtrueに設定します。

FHIR_BUNDLE_CAPABILITIES

未設定

カンマ区切りのBundleタイプ: batchtransactionbundleツールを有効にします。

FHIR_BUNDLE_WRITES_ENABLED

false

Bundle内の書き込みエントリを許可するにはtrueに設定します(FHIR_WRITE_CAPABILITIESも必要)

FHIR_OPERATIONS

未設定

カンマ区切りの操作キー。noneはすべてのカタログ操作を無効にします。デフォルトのカタログ: everythinglastnvalidatedocrefexpandlookuptranslatesummarymatch

FHIR_TERMINOLOGY_BASE_URL

未設定

用語ツールを有効にします。例: https://tx.fhir.org/r4

FHIR_PAGINATION_PATHS

未設定

ページネーションリンク用の追加の許可パスプレフィックス。例: FHIRProxy

FHIR_PREFETCH_MAX_PAGES

5

合体されたコンパクト検索ごとに取得される最大アップストリームページ数

FHIR_PREFETCH_MAX_ENTRIES

5000

停止するまでに蓄積される最大アップストリームエントリ数

FHIR_PREFETCH_MAX_BYTES

2097152

停止するまでに取得される最大生バイト数

FHIR_PREFETCH_TIMEOUT_MS

25000

合体ループのウォールクロック予算

FHIR_AUDIT_SINK

未設定

consolefilehttpの任意の組み合わせ

FHIR_AUDIT_FILE

./audit.jsonl

file監査シンクが有効なときに使用されるJSONLファイル

FHIR_AUDIT_HTTP_URL

未設定

http監査シンクの宛先URL。httpが有効なときに必須

FHIR_AUDIT_HTTP_FORMAT

raw

raw(内部AuditEvent JSON)またはfhir-auditevent(FHIR R4 AuditEvent)

FHIR_AUDIT_HTTP_AUTH

未設定

httpシンクがそのまま送信するAuthorizationヘッダー値

FHIR_AUDIT_USER_HEADER

未設定

監査イベントにコピーされるプロキシ認証ユーザーヘッダー

LOG_LEVEL

info

ログの詳細度: errorwarninfo、またはdebug

明示的なFHIR_SERVER_URLFHIR_TOKEN_URLの値は、派生URLよりも常に優先されます。

FHIRバージョンサポート

Set FHIR_VERSION を設定して、アクティブな R4+ FHIR リリースを選択します。これは、導出される FHIR API URL、FHIRPath モデルコンテキスト、およびコンパクトなレスポンスモデルのメタデータを制御します。一部のリリースでは、最も近い互換性のある FHIRPath モデルが使用される場合があります。用語については、選択した FHIR リリースに一致するエンドポイントを使用してください。起動時ログは、明示的な FHIR または用語の URL が異なるバージョンを参照しているように見える場合にヒントを示します。

ツールとメッセージのカスタマイズ

config/ 配下のすべては、ソースを変更せずにカスタマイズできます。

設定は部分オーバーレイとして解決されます:各ファイルについて、カレントワーキングディレクトリ内の ./config/<file>(存在する場合)がパッケージされたデフォルトを上書きし、省略したものは組み込みのデフォルトにフォールバックします。つまり、npm インストールはそのまま動作し、カスタマイズするには、サーバーを起動する場所の隣に、変更したいファイルだけを含む ./config フォルダを配置します。

オーバーレイには2つの粒度があります:

  • ファイル全体resources/*.jsonoperations.jsonsearch-controls.jsoncore-tools.jsoninstructions/*):提供したファイルがパッケージされたファイルを完全に置き換えます。新しいリソースファイル(例:./config/resources/myresource.json)はツールを追加します。オーバーレイは上書きと追加はできますが、パッケージされたリソースを削除することはできません — 厳密に最小限のカタログを出荷するには、パッケージされた config/resources/ ファイルを削除してください(compose の例を参照)。

  • キー単位messages/*.json):ローカルファイルは、それが含む個々のキーのみを上書きします。その他のキーはすべてパッケージされたデフォルトにフォールバックします。したがって、ファイル全体をコピーすることなく、単一の説明やメッセージを調整できます。不明なキー、空の値、および不正な JSON は、タイプミスを検出するために起動時に即座に失敗します。

messages/*.json ファイルはプロセス起動時に一度だけ読み込まれます。変更を有効にするには、サーバーの再起動(および、ツールスキーマやインストラクションの場合はクライアントの再接続)が必要です。リソース、検索コントロール、およびオペレーションの開発時ホットリロードについては後述します。

File

Purpose

resources/*.json

FHIR リソースツール(リソースごとに1ファイル):検索パラメータ、直接読み取り動作、および requireOneOf ルール

operations.json

operate の名前付きオペレーションカタログ(オペレーションごとの説明とメモ)

search-controls.json

_count_sort_summary_elements_include_revinclude_lastUpdatedfhirpathresponseModemaxResults、および prefetch の説明

messages/output-schema.json

すべてのツールの outputSchema フィールドの説明(キー単位のオーバーレイ)

messages/input-schema.json

生成されるリソース入力パラメータ(_id_vid_since_atactionbody)と operate ツールのタイトルおよびパラメータの説明(キー単位のオーバーレイ)

instructions/manifest.json

構成するインストラクションフラグメントの順序付きリスト。各フラグメントにはオプションの when ゲート(terminologywritesoperationsbundle)があります。カスタムビルドでは、このファイルを編集してセクションの並べ替え、追加、または削除ができます。

instructions/*.md

マニフェストによって参照されるインストラクションフラグメント。ゲートされたセクションは、その機能が有効な場合にのみ含まれます。{{OPERATIONS_LIST}} トークンはライブのオペレーションカタログに置き換えられます。

messages/*.json

ユーザー向けメッセージ、エラー、およびレスポンスノート(キー単位のオーバーレイ。ドメインごとに分割:core、write、operations、terminology、bundle、artifact)

core-tools.json

組み込みツールの説明とパラメータヒント

リソース定義スキーマ

config/resources/ 内の各ファイルは、単一のリソース定義オブジェクトです。ファイルはファイル名順にスキャンされます。ファイル名は慣例として小文字のリソース名です(例:patient.json)。各オブジェクトには次のフィールドがあります:

Field

Type

Description

resource

string

FHIR リソースタイプ

toolName

string

MCP ツール名。一意である必要があります

description

string

ツールの説明

supportsDirectRead

boolean

_id による GET /ResourceType/{id} を有効にします

searchParams

Record<string,string>

FHIR 検索パラメータと説明

requireOneOf

(string | string[])[]

検索には少なくとも1つのオプションが必要です。文字列は単一の必須パラメータです。ネストされた配列は、すべてのパラメータが必須のパラメータセットです。["patient"]patient を受け付けます。[["given","family"],["identifier"]]given+family の組み合わせ、または identifier を受け付けます。

searchParams の値は説明であり、完全な FHIR ケイパビリティモデルではありません。サーバ固有の検索動作が適用される場合があります。

ホットリロード

開発時(NODE_ENVproduction ではない場合)、config/resources/ フォルダ、search-controls.json、および operations.json が監視されます。無効な JSON の場合は、最後に有効だったスナップショットが保持されます。実質的な変更を伴うリロードはトラんザクション的に適用されます:派生した SMART スコープが変更された場合、新しい定義とツール登録がコミットされる前に対換トークンが取得されるため、取得に失敗した場合、実行中のカタログは変更されません。ツールの追/削除、オペレーションおよびパラメータ名のスキーマ変更はライブで再登録されます — 再起動は不要です。意味的に変更のない保あ存ではリフレッシュは発生しません。本番環境では設あ定は起動時に一度だけ読込まれますが、実行時の /metadata の変更(capabilities(refresh=true) による)またはトークンリフレッシュ時のバックエンドの SMART スコープ変更により、利可用なツールがあらゆるモードで再評価されます。

回避できない境界が1つあります:ツールリストとスキーマはホットリフレッシュされますが、サーバーの instructions は MCP initialize 中に一度だけ送信され、既存の接続では置換えることができません。変更されたインストラクションテキストを受取るには、クライアントは再接続/再初期化する必要があります。

トランスポート

Stdio

MCP_TRANSPORT=stdio を設あ定します。stdout は MCP プロトコル用に予約されており、ログは stderr にリダイレクトされます。stdio デプロイメントでは外部の FHIR_JWKS_URL を使用してください。

Streamable HTTP

HTTP トランスポートはステートレスで、MCP を次の場所に公開します:

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

MCP クライアント設定:

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

GET /health は、PHI を含まない readiness スナップショットを返します:

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

認可が有効な場合、authz はアクティブなプロバイダーを報告し、tools は登録済みツール数が呼び出し元に固有であるため省略されます。

localhost を超えて HTTP を公開する場合は、TLS とユーザー認証にリバースプロキシを使用してください。パブリックインターフェースにバインドする場合は ALLOWED_HOSTS を設定します。

呼び出し元ごとの認可(Entra、オプション)

デフォルト(MCP_AUTHZ=none)では、すべての呼び出し元は /metadata とバックエンドの SMART スコープによってのみ制限された完全なツールセットを参照できます。MCP_AUTHZ=entra を設あ定すると、オプションの呼び出し元ごとのレイヤーが追あ加されます:各 /mcp リクエストは、Microsoft Entra によって発行された Authorization: Bearer <token> を保あ持している必あ要があり、呼び出し元のアプリロールがそのリクエストに対してどのツールが構あ築されるかを決あ定します。これは MCP レイヤーの認可のみです — FHIR サーバー自あ身の認可を決して置換えるものではなく、バックエンドの SMART トークンと設あ定がすでに許可しているものから差引くことしかできません。

API アプの登録では、マニフェストで requestedAccessTokenVersion2 に設あ定する必あ要があります。プロバイダーはテナント固有の v2 発行者を検証し、MCP_ENTRA_AUDIENCE が API アプリケーションのクライアント ID であることを期待します。

呼び出し元がロールを持たないツールはまったく登録されません — 単にブロックされるのではなく、tools/list に存在しません。ヘルパーツール(capabilitiespaginateterminology_lookupcode_search)は決してゲートされません。

アプリロールの値(デフォルトの FhirHydrant プレフィックス付き):

Role

Grants

FhirHydrant.<Resource>.Read

そのリソースの search、read、vread、history

FhirHydrant.<Resource>.Write

read アクションに加えて create、update、patch、delete(FHIR_WRITE_CAPABILITIES に従う)

FhirHydrant.Operation.<key>

operate ツールを介した名前付きオペレーション(例:FhirHydrant.Operation.everything

FhirHydrant.Bundle

bundle ツール

FhirHydrant.SystemHistory.Read

システム全体の system_history ツール

FhirHydrant.Admin

上記のすべて。ただし、バックエンドの SMART スコープ、/metadata、および write/bundle/operation 設定によって制限されます

HTTP トランスポートが必要です。MCP_TRANSPORT=stdio での MCP_AUTHZ=entra は起動時に失敗します。ベアラートークンがない、または無効な場合、401 を受け取ります。

認可プロバイダーの追加

Entra は同梱されている唯一のプロバイダーですが、認可レイヤーはプロバイダーに依存しません。これはソース拡張であり、ランタイムプラグインではありません:npm パッケージには bin/server.js のみが同梱されており(プロバイダーはバンドルされています)、プロバイダーを追加するにはリポジトリをフォークまたはクローンして再ビルドする必要があります。

共有パイプラインはプロバイダー非依存です。プロバイダーはAuthorizationヘッダーを{ subject, roles }にマッピングするだけです。ロール語彙(.Read/.Write/Operation.<key>/Bundle/SystemHistory.Read/Admin)とMCP_ROLE_PREFIXの処理は、すべてのプロバイダーに対してdecideAuthzによって適用されます。

プロバイダーを追加する(例:auth0)には、2つの編集だけで済みます:

  1. ts/mcp/authz/auth0.tsを作成し、AuthzProviderをエクスポートします。validate(authorization)を実装して{ subject, roles }を返します(拒否する場合はスロー)。また、必要に応じてvalidateConfig()を実装し、プロバイダー固有の環境変数が不足している場合に早期失敗させます。プロバイダー固有の環境変数はすべてこのモジュール内に保持し、Configにフィールドを追加しないでください。

  2. ts/mcp/authz/registry.tsに1エントリを追加します: auth0: () => import("./auth0.ts").then((m) => m.auth0Provider)

これだけです。AuthzMode型、MCP_AUTHZパーサー、およびそのエラーメッセージはすべてレジストリのキーから自動的に導出されるため、MCP_AUTHZ=auth0は完全な型安全性を備えてそのまま動作します。他のファイルを変更する必要はありません。

デプロイ例

examples/ディレクトリには、Docker Compose、リバースプロキシ(Caddy)、Azure Container Apps、Azure App Service、Kubernetes向けのスタンドアロンのデプロイ例があります。各例にはnpmからインストールするDockerfileと、さまざまな設定ファイルをオーバーライドする方法を示すconfig/オーバーレイが含まれています。

開発

# dev server
npm run dev

# type-check
npm run check

# build and run
npm run build
npm start

ビルド出力はbin/server.jsに出力されます。

Related MCP Connectors

Related MCP Servers

  • A
    license
    A
    quality
    C
    maintenance
    Provides seamless integration with FHIR APIs, enabling AI/LLM tools to search, retrieve, and analyze clinical healthcare data with support for SMART-on-FHIR authentication and multiple transport protocols.
    7
    134
    Apache 2.0
  • F
    license
    Not graded
    quality
    D
    maintenance
    Enables AI assistants to securely interact with FHIR R4 servers for clinical decision support workflows, including PlanDefinition execution, FHIR resource management, terminology services, and Questionnaire/StructureMap transformation via Matchbox.
    1

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/faulkj/fhirHydrant'

If you have feedback or need assistance with the MCP directory API, please join our Discord server