fhirHydrant
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 buildMCP クライアント設定
デスクトップ 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 |
| サーバーがシステムレベルの | すべてのリソースタイプにわたるシステムレベルの変更履歴を取得 |
| 常に登録 | CapabilityStatement の概要、登録済みツール、スキップされたツール、検索パラメータ、オペレーション、メタデータノートを検査 |
| 常に登録 | サーバーが返した |
| 少なくとも 1 つの名前付きオペレーションがゲーティングを通過する場合 | 臨床データ、用語、IPS、マッチング、検証、またはカスタムワークフローのための設定済み FHIR 名前付きオペレーションを呼び出す |
|
| FHIR バッチまたはトランザクション Bundle を送信; 書き込みには追加のオプトインが必要 |
|
| 1 つの LOINC または SNOMED CT コードを検索 |
|
| テキストで 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 は、リソースが 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 を設定して有効にします:
ツール | 説明 |
| 1 つの LOINC または SNOMED CT コードを検索 |
| ページングサポート付きのテキストフィルターでコードを検索 |
これらのツールは、設定された用語サーバーを直接呼び出します。臨床 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=trueとFHIR_WRITE_CAPABILITIES内の対応するアクションが必要です。トランザクション Bundle には、明示的な
FHIR_BUNDLE_CAPABILITIES=transactionが必要です。すべてのエントリは、設定されたリソース、SMART スコープ、メタデータインタラクションに対して事前チェックされます。単一のエントリが失敗した場合、Bundle 全体が送信前に拒否されます。
V1 の除外: 条件付きリクエスト、システムレベルの _history、絶対 URL、Bundle エントリ内の $operation URL はサポートされていません。
Bundle 内の履歴: vread(Resource/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サーバーがサーバー側の制御を提供している場合はそれを利用します。
機能 | 動作 |
| デフォルトでは |
ページ結合 | コンパクトモードが有効な場合、サーバーは複数の上流ページを順次取得し、各ページを即座に圧縮して、1つの統合されたBundleを返します。 |
バイト制限 |
|
自動リトライ | サイズ超過の検索Bundleは、まずローカルでのチャンク分割を試み、次にフォールバックとしてより小さい |
FHIRPath |
|
コンパクトモード |
|
フルモード |
|
ロックされたコンパクト |
|
ネイティブアーティファクト | 非JSONレスポンス(ドキュメント、画像、DICOM、RTF、HTML、XML、CSV、NDJSON、ZIP、octet-stream)およびJSON FHIR Binaryは、メタデータエンベロープと1つのMCP埋め込みテキスト/BLOBリソースに正規化されます。 |
コンパクト出力は、AI向けのJSONであり、標準的なFHIRではありません。meta、ナラティブ、拡張、CodeableConcept、Reference、QuantityなどのFHIRノイズや一般的なデータ型、およびCodeableReferenceなどの新しいデータ型を削除または簡素化します。
FHIRPathはローカルで実行されるため、FHIRサーバーが式を見ることはありません。評価に失敗した場合、生のレスポンスは返されず、エラーが返されます。
構造化レスポンスエンベロープ
すべてのFHIRデータツール(リソースツール、paginate、operate、bundle、system_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は、console、file、httpの任意の組み合わせに設定します。
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文字)から自動的に導出され、起動時にログに記録されます。
キーローテーションのワークフロー:
新しいキー(RSA-2048またはEC P-384)を生成します。
新しいPEMを
FHIR_RETIRED_KEYSに追加して再デプロイし、JWKSに両方が含まれるようにします。新しい
kid(起動時にログに記録されます)を認証サーバーに登録します。新しいPEMを
FHIR_ACTIVE_KEYに移動し、古いPEMをFHIR_RETIRED_KEYSに移動します。再デプロイします。認証サーバーのキャッシュが期限切れになったら、
FHIR_RETIRED_KEYSから古いキーを削除します。
外部JWKSを使用する場合は、FHIR_ACTIVE_KEYを切り替える前に新しい公開キーを公開してください。
環境変数
完全なサンプルについては、.env.exampleを参照してください。
必須
変数 | 説明 |
| FHIRサーバーのURLとトークンURLを導出するために使用されるベースURL。 |
| SMART Backend ServicesのクライアントID( |
| Base64エンコードされたPKCS#8 PEM署名キー(RSAまたはEC P-384)。( |
オプション
変数 | デフォルト | 説明 |
|
|
|
| 未設定 | JWKSローテーション用のカンマ区切りのbase64エンコードされたPEM |
|
| アクティブなR4+ FHIRリリース。派生URL、FHIRPathモデル、コンパクトモデルのメタデータを制御します。 |
|
| 明示的なFHIR API URLの上書き |
|
| 明示的なトークンエンドポイントの上書き |
| 未設定 | 外部JWKS URL。HTTPモードでは省略すると組み込みの |
|
|
|
|
| HTTPリスナーポート |
|
| HTTPバインドアドレス |
| 未設定 | DNSリバインディング保護用のカンマ区切りのホスト名 |
|
|
|
|
| 許可された場合に検索に注入されるデフォルトの |
|
| 明示的な呼び出し元の |
|
| モデル向けJSONレスポンスのバイト制限。サイズ超過のBundleはチャンク化されます。 |
|
| ネイティブ/バイナリアーティファクト本文用の個別のバイト上限(MiB)。JSON制限とは独立(base64転送で約+33%) |
|
| 送信FHIRリクエストの試行ごとのタイムアウト |
|
| 受け入れ可能なMCPリクエスト本文の最大サイズ(Express json limit文字列)。大きな書き込み/バンドルペイロードが拒否される場合は引き上げてください。 |
|
| 認可プロバイダー: |
|
| 付与されたロール値のプレフィックス(例: |
| 未設定 | EntraテナントGUID(ドメインエイリアスではありません)。 |
| 未設定 | v2アクセストークンの |
| 未設定 |
|
| 未設定 | カンマ区切りの書き込みアクション: |
|
|
|
|
| FHIRサーバーに対して実行せずに書き込みを検証してログに記録するには |
| 未設定 | カンマ区切りのBundleタイプ: |
|
| Bundle内の書き込みエントリを許可するには |
| 未設定 | カンマ区切りの操作キー。 |
| 未設定 | 用語ツールを有効にします。例: |
| 未設定 | ページネーションリンク用の追加の許可パスプレフィックス。例: |
|
| 合体されたコンパクト検索ごとに取得される最大アップストリームページ数 |
|
| 停止するまでに蓄積される最大アップストリームエントリ数 |
|
| 停止するまでに取得される最大生バイト数 |
|
| 合体ループのウォールクロック予算 |
| 未設定 |
|
|
|
|
| 未設定 |
|
|
|
|
| 未設定 |
|
| 未設定 | 監査イベントにコピーされるプロキシ認証ユーザーヘッダー |
|
| ログの詳細度: |
明示的なFHIR_SERVER_URLとFHIR_TOKEN_URLの値は、派生URLよりも常に優先されます。
FHIRバージョンサポート
Set FHIR_VERSION を設定して、アクティブな R4+ FHIR リリースを選択します。これは、導出される FHIR API URL、FHIRPath モデルコンテキスト、およびコンパクトなレスポンスモデルのメタデータを制御します。一部のリリースでは、最も近い互換性のある FHIRPath モデルが使用される場合があります。用語については、選択した FHIR リリースに一致するエンドポイントを使用してください。起動時ログは、明示的な FHIR または用語の URL が異なるバージョンを参照しているように見える場合にヒントを示します。
ツールとメッセージのカスタマイズ
config/ 配下のすべては、ソースを変更せずにカスタマイズできます。
設定は部分オーバーレイとして解決されます:各ファイルについて、カレントワーキングディレクトリ内の ./config/<file>(存在する場合)がパッケージされたデフォルトを上書きし、省略したものは組み込みのデフォルトにフォールバックします。つまり、npm インストールはそのまま動作し、カスタマイズするには、サーバーを起動する場所の隣に、変更したいファイルだけを含む ./config フォルダを配置します。
オーバーレイには2つの粒度があります:
ファイル全体(
resources/*.json、operations.json、search-controls.json、core-tools.json、instructions/*):提供したファイルがパッケージされたファイルを完全に置き換えます。新しいリソースファイル(例:./config/resources/myresource.json)はツールを追加します。オーバーレイは上書きと追加はできますが、パッケージされたリソースを削除することはできません — 厳密に最小限のカタログを出荷するには、パッケージされたconfig/resources/ファイルを削除してください(compose の例を参照)。キー単位(
messages/*.json):ローカルファイルは、それが含む個々のキーのみを上書きします。その他のキーはすべてパッケージされたデフォルトにフォールバックします。したがって、ファイル全体をコピーすることなく、単一の説明やメッセージを調整できます。不明なキー、空の値、および不正な JSON は、タイプミスを検出するために起動時に即座に失敗します。
messages/*.json ファイルはプロセス起動時に一度だけ読み込まれます。変更を有効にするには、サーバーの再起動(および、ツールスキーマやインストラクションの場合はクライアントの再接続)が必要です。リソース、検索コントロール、およびオペレーションの開発時ホットリロードについては後述します。
File | Purpose |
| FHIR リソースツール(リソースごとに1ファイル):検索パラメータ、直接読み取り動作、および |
|
|
|
|
| すべてのツールの |
| 生成されるリソース入力パラメータ( |
| 構成するインストラクションフラグメントの順序付きリスト。各フラグメントにはオプションの |
| マニフェストによって参照されるインストラクションフラグメント。ゲートされたセクションは、その機能が有効な場合にのみ含まれます。 |
| ユーザー向けメッセージ、エラー、およびレスポンスノート(キー単位のオーバーレイ。ドメインごとに分割:core、write、operations、terminology、bundle、artifact) |
| 組み込みツールの説明とパラメータヒント |
リソース定義スキーマ
config/resources/ 内の各ファイルは、単一のリソース定義オブジェクトです。ファイルはファイル名順にスキャンされます。ファイル名は慣例として小文字のリソース名です(例:patient.json)。各オブジェクトには次のフィールドがあります:
Field | Type | Description |
|
| FHIR リソースタイプ |
|
| MCP ツール名。一意である必要があります |
|
| ツールの説明 |
|
|
|
|
| FHIR 検索パラメータと説明 |
|
| 検索には少なくとも1つのオプションが必要です。文字列は単一の必須パラメータです。ネストされた配列は、すべてのパラメータが必須のパラメータセットです。 |
searchParams の値は説明であり、完全な FHIR ケイパビリティモデルではありません。サーバ固有の検索動作が適用される場合があります。
ホットリロード
開発時(NODE_ENV が production ではない場合)、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/jsonMCP クライアント設定:
{
"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 アプの登録では、マニフェストで requestedAccessTokenVersion を 2 に設あ定する必あ要があります。プロバイダーはテナント固有の v2 発行者を検証し、MCP_ENTRA_AUDIENCE が API アプリケーションのクライアント ID であることを期待します。
呼び出し元がロールを持たないツールはまったく登録されません — 単にブロックされるのではなく、tools/list に存在しません。ヘルパーツール(capabilities、paginate、terminology_lookup、code_search)は決してゲートされません。
アプリロールの値(デフォルトの FhirHydrant プレフィックス付き):
Role | Grants |
| そのリソースの search、read、vread、history |
| read アクションに加えて create、update、patch、delete( |
|
|
|
|
| システム全体の |
| 上記のすべて。ただし、バックエンドの SMART スコープ、 |
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つの編集だけで済みます:
ts/mcp/authz/auth0.tsを作成し、AuthzProviderをエクスポートします。validate(authorization)を実装して{ subject, roles }を返します(拒否する場合はスロー)。また、必要に応じてvalidateConfig()を実装し、プロバイダー固有の環境変数が不足している場合に早期失敗させます。プロバイダー固有の環境変数はすべてこのモジュール内に保持し、Configにフィールドを追加しないでください。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に出力されます。
This server cannot be installed
Maintenance
Related MCP Connectors
Hosted MCP server for the Healthie EHR & telehealth API: patients, appointments, charting, tasks.
Securely access and manage FHIR healthcare data stored in Medplum.
Governed MCP gateway: one endpoint for your tools, with credential custody and audit log.
Governed data discovery, exact queries, decisions, simulations, and runtime utilities over MCP.
Related MCP Servers
- AlicenseAqualityCmaintenanceProvides 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.7134Apache 2.0
- FlicenseNot gradedqualityDmaintenanceEnables 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
- AlicenseNot gradedqualityDmaintenanceEnables interaction with FHIR servers to access, search, and manage FHIR resources, including appointment scheduling and cancellation.1MIT

LangCare MCP FHIR Serverofficial
AlicenseNot gradedqualityDmaintenanceEnterprise-grade MCP Server for FHIR-based EMRs. Enables AI agents to read, search, create, and update any FHIR R4 resource across major EHR systems like EPIC, Cerner, and OpenEMR.14753MIT
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
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