fhirHydrant: FHIR MCP 서버

R4+ FHIR API를 위한 현대적이고 완전히 구성 가능한 오픈소스 Node.js MCP 서버입니다. 서명된 JWT 클라이언트 자격 증명을 사용하여 SMART on FHIR v2 Backend Services를 통해 MCP 호환 클라이언트를 임상 데이터에 연결합니다.

fhirHydrant는 FHIR 리소스, 명명된 작업, 용어 조회, 페이지네이션을 MCP 도구로 변환합니다. 기본 리소스와 작업은 시작점에 불과합니다. 리소스, 작업, 검색 제어, 지침, 메시지는 소스 변경 없이 구성 파일을 통해 확장, 축소, 교체할 수 있습니다.

• JWKS 호스팅, 키 교체, 토큰 갱신, 동적 범위를 지원하는 SMART Backend Services 인증

• 검색, 직접 읽기, vread, history 및 선택적 메타데이터 기반 CRUD를 위한 구성 가능한 리소스 도구

• 임상 데이터, 용어, IPS, 환자 매칭, 검증, 사용자 지정 워크플로를 위한 구성 기반 명명된 작업

• CapabilityStatement 인식 도구, 검색 제어, 작업 게이팅, 런타임 범위 검사

• 토큰 경제 기능: 컴팩트 응답, FHIRPath 필터링, 바이트 제한, _count 셰이핑, 대용량 Bundle 재시도

• 선택적 용어 도구, PHI 경량 감사 이벤트(기본적으로 리소스 콘텐츠 없음), stdio 또는 Streamable HTTP 전송

참고: MCP 도구 호출을 통해 반환되는 FHIR 데이터에는 PHI가 포함될 수 있습니다. MCP 클라이언트의 대화 내용 저장 및 로깅 동작이 규정 준수 요구 사항과 일치하는지 확인하세요.

목차

• 빠른 시작

• 도구

• 메타데이터 및 범위 게이팅

• 토큰 경제 및 응답 셰이핑

• 감사 이벤트

• SMART 백엔드 인증 및 키

• 환경 변수

• FHIR 버전 지원

• 도구 및 메시지 사용자 지정

• 전송

• 배포 예시

• 개발

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가 SMART 인증과 함께 HTTP로 실행될 때만 사용할 수 있습니다.

설치

# 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는 base64로 인코딩된 PKCS#8 개인 키(RSA 또는 EC P-384)입니다. kid는 시작 시 잘린 JWK Thumbprint를 통해 자동으로 파생되어 콘솔에 기록됩니다.

인증 없는 액세스

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, 쓰기 설정, 작업 설정, 용어 설정에 따라 달라집니다.

리소스 도구

리소스 도구는 config/resources/ 폴더에서 생성됩니다. 리소스당 JSON 파일 하나(예: patient.json)이며 시작 시 스캔됩니다. 제공되는 구성은 일반적인 임상, 관리, 약물, 의료인, 조직, 문서 리소스를 다룹니다. 파일을 추가하면 리소스가 추가되고, 파일을 삭제하면 리소스가 제거됩니다. 소스 변경이 필요 없습니다.

각 리소스 도구는 구성된 검색 매개변수, _id를 사용한 선택적 직접 읽기, fhirpath, 그리고 컴팩트 잠금이 아닌 경우 responseMode를 지원합니다. 직접 읽기는 _id가 유일한 비어 있지 않은 인수일 때만 수행되며, _id에 다른 매개변수가 함께 있으면 검색으로 유지되므로 호출자의 의도가 조용히 무시되지 않습니다.

리소스 도구는 기본적으로 검색/읽기입니다. 메타데이터 기반 CRUD 작업을 활성화하려면 FHIR_WRITE_CAPABILITIES를 설정하세요:

FHIR_WRITE_CAPABILITIES=create,update,patch,delete

vread는 리소스에 supportsDirectRead가 있고 서버가 vread 상호작용을 광고할 때 사용할 수 있습니다. history는 서버가 history-instance 또는 history-type을 광고할 때 사용할 수 있습니다. 둘 다 SMART r 권한이 필요합니다. 선택적 _since 및 _at 매개변수는 history 결과를 필터링합니다. history 응답은 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을 사용하여 Bundle 페이지 하나를 가져옵니다. 컴팩트 모드가 활성화되어 있고 가져온 페이지에 더 많은 결과가 있는 경우 paginate는 여러 업스트림 페이지를 하나의 컴팩트 응답으로 자동 병합합니다(리소스 검색 도구와 동일한 동작). prefetch=false를 전달하면 병합을 비활성화하고 단일 페이지를 얻을 수 있습니다.

명명된 작업

operate 도구는 config/operations.json의 FHIR 명명된 작업을 호출합니다. 제공되는 작업 카탈로그는 임상 집계, 검증, 문서 조회, 용어 작업, IPS 생성, 환자 매칭을 다룹니다. 소스 변경 없이 작업 카탈로그를 확장, 축소, 교체 또는 비활성화할 수 있습니다.

용어 도구

FHIR_TERMINOLOGY_BASE_URL을 설정하여 활성화하세요:

이 도구들은 구성된 용어 서버를 직접 호출합니다. 임상 FHIR 서버 자격 증명을 사용하지 않습니다. 선택한 FHIR 릴리스와 일치하는 용어 엔드포인트(예: https://tx.fhir.org/r4)를 사용하세요.

Bundle 실행

bundle을 활성화하려면 FHIR_BUNDLE_CAPABILITIES=batch (또는 batch,transaction)를 설정하세요. 이 도구는 FHIR batch 또는 transaction Bundle을 제출하고 표준 응답 파이프라인을 통해 서버의 응답을 반환합니다.

안전 모델:

• 읽기 전용 batch Bundle(모든 GET 항목)은 FHIR_BUNDLE_CAPABILITIES=batch만으로 허용됩니다.

• 쓰기 항목(POST, PUT, PATCH, DELETE)은 추가로 FHIR_BUNDLE_WRITES_ENABLED=true와 FHIR_WRITE_CAPABILITIES의 해당 작업이 필요합니다.

• transaction Bundle에는 명시적 FHIR_BUNDLE_CAPABILITIES=transaction이 필요합니다.

• 모든 항목은 구성된 리소스, SMART 범위, 메타데이터 상호작용에 대해 사전 검사됩니다. 단 하나의 항목이라도 실패하면 제출 전에 전체 Bundle이 거부됩니다.

V1 제외 사항: Bundle 항목 내의 조건부 요청, 시스템 수준 _history, 절대 URL, $operation URL은 지원되지 않습니다.

Bundle의 History: vread (Resource/id/_history/vid), 인스턴스 history (Resource/id/_history), 유형 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 서버가 이를 광고하는 경우 서버 측 제어를 사용합니다.

컴팩트 출력은 AI 지향 JSON이지 표준 FHIR이 아닙니다. meta, 내러티브, 확장, CodeableConcept, Reference, Quantity 및 CodeableReference와 같은 최신 데이터 유형 등 FHIR 노이즈와 일반적인 데이터 유형을 제거하거나 단순화합니다. FHIRPath는 로컬에서 실행되며 FHIR 서버는 표현식을 볼 수 없습니다. 평가가 실패하면 원시 응답은 보류되고 오류가 반환됩니다.

구조화된 응답 봉투

모든 FHIR 데이터 도구(리소스 도구, paginate, operate, bundle, system_history)는 각 도구의 outputSchema를 통해 광고되고 structuredContent로 반환되는 단일 구조화된 봉투를 반환합니다(텍스트 콘텐츠는 동일한 봉투의 직렬화된 형태입니다). FHIR 페이로드(data)와 함께 메타데이터(응답 모드, hasMore/continuation 페이지네이션 신호, Bundle 및 병합 통계, 사람이 읽을 수 있는 notes)를 전달합니다. 전체 필드 목록은 도구의 outputSchema입니다.

크기가 큰 응답은 가능한 경우 청크됩니다(data는 보존되며 continuation을 통해 검색 가능). 청크할 수 없으면 봉투는 data가 생략된 status: "truncated"로 표시됩니다. 잘림은 오류가 아니라 성공했지만 부분적인 결과입니다. 기능 및 용어 도구는 이 FHIR 봉투 대신 자체 구조화된 형태를 반환합니다.

페이지 병합

검색(리소스 도구 또는 paginate)에 컴팩트 모드가 활성화되면 서버가 여러 업스트림 FHIR 페이지를 순차적으로 가져와 각 페이지를 즉시 컴팩트하고 하나의 통합 컴팩트 Bundle로 반환합니다. 이렇게 하면 여러 번의 "다음 페이지" 호출이 한 번으로 줄어 MCP 왕복이 감소합니다.

• maxResults는 목표를 설정합니다 — 서버는 이 임계값을 넘으면 가져오기를 중지합니다(전체 페이지가 추가되므로 약간 초과할 수 있음)

• prefetch=false는 한 번의 호출에 대해 병합을 비활성화합니다

• _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초 타임아웃의 fire-and-forget 방식입니다. 전송 실패는 기록되며 도구 응답에 영향을 미치지 않습니다.

감사 이벤트에는 타임스탬프, 도구, 해당하는 경우 리소스 유형, 작업, 상태, 기간, 응답 크기, 페이지네이션 요약, 요청 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 모드에서 내장 /jwks 엔드포인트는 FHIR_JWKS_URL이 설정되지 않은 경우 활성 키와 폐기된 키의 공개 키를 노출합니다. 각 키의 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_SERVER_URL 및 FHIR_TOKEN_URL 값은 항상 파생 URL보다 우선합니다.

FHIR 버전 지원

FHIR_VERSION을 설정하여 활성 R4+ FHIR 릴리스를 선택합니다. 이 값은 파생된 FHIR API URL, FHIRPath 모델 컨텍스트, 그리고 간결한 응답 모델 메타데이터를 제어합니다. 일부 릴리스는 가장 가까운 호환 FHIRPath 모델을 사용할 수 있습니다. 용어(terminology)의 경우 선택한 FHIR 릴리스와 일치하는 엔드포인트를 사용하십시오. 명시적 FHIR 또는 용어 URL이 다른 버전을 참조하는 것으로 보이면 시작 로그에 힌트가 표시됩니다.

도구 및 메시지 사용자 지정

config/ 아래의 모든 것은 소스 변경 없이 사용자 지정할 수 있습니다.

구성은 부분 오버레이(partial overlay) 방식으로 해석됩니다. 각 파일에 대해 현재 작업 디렉터리의 ./config/<file>이 있으면(있는 경우) 패키징된 기본값을 재정의하고, 생략한 항목은 기본 제공 기본값으로 대체됩니다. 따라서 npm 설치가 기본적으로 바로 작동하며, 사용자 지정하려면 서버를 시작하는 위치에 변경하려는 파일만 포함된 ./config 폴더를 두면 됩니다.

오버레이에는 두 가지 세분화 수준이 있습니다.

• 전체 파일(resources/*.json, operations.json, search-controls.json, core-tools.json, instructions/*): 제공한 파일이 패키징된 파일을 완전히 대체합니다. 새 리소스 파일(예: ./config/resources/myresource.json)은 도구를 추가합니다. 오버레이는 패키징된 리소스를 재정의하고 추가할 수 있지만 제거할 수는 없습니다. 엄격히 최소한의 카탈로그를 제공하려면 패키징된 config/resources/ 파일을 제거하십시오(compose 예제 참조).

• 키별(messages/*.json): 로컬 파일은 포함된 개별 키만 재정의하며, 다른 모든 키는 패키징된 기본값으로 대체됩니다. 따라서 전체 파일을 복사하지 않고도 단일 설명이나 메시지를 조정할 수 있습니다. 알 수 없는 키, 빈 값, 잘못된 형식의 JSON은 시작 시 빠르게 실패하여 오타를 잡아냅니다.

messages/*.json 파일은 프로세스 시작 시 한 번 읽힙니다. 변경하려면 서버 재시작이 필요하며(도구 스키마나 지침의 경우 클라이언트 재연결도 필요), 변경 사항이 적용됩니다. 리소스, 검색 컨트롤, 작업에 대한 개발 핫 리로드는 아래에 설명되어 있습니다.

리소스 정의 스키마

config/resources/의 각 파일은 단일 리소스 정의 객체입니다. 파일은 파일 이름 순서로 스캔됩니다. 파일 이름은 관례적으로 소문자 리소스 이름입니다(예: patient.json). 각 객체에는 다음 필드가 있습니다.

searchParams 값은 설명이지 완전한 FHIR 기능 모델이 아닙니다. 서버별 검색 동작이 여전히 적용될 수 있습니다.

핫 리로드

개발 모드(NODE_ENV가 production이 아닌 경우)에서는 config/resources/ 폴더, search-controls.json, operations.json이 감시됩니다. 잘못된 JSON은 마지막 유효한 스냅샷을 유지합니다. 실질적으로 변경된 리로드는 트랜잭션 방식으로 적용됩니다. 파생된 SMART 범위가 변경되면 새 정의와 도구 등록이 커밋되기 전에 교체 토큰이 획득되므로, 획득에 실패하면 실행 중인 카탈로그는 그대로 유지됩니다. 도구 추가/제거, 작업 및 매개변수 이름 스키마 변경은 재시작 없이 실시간으로 다시 등록됩니다. 의미적으로 변경되지 않은 저장은 새로 고침을 발생시키지 않습니다. 프로덕션은 시작 시 구성을 한 번 읽지만, 런타임 /metadata 변경(capabilities(refresh=true)를 통한) 또는 토큰 갱신 시 백엔드 SMART 범위 변경은 모든 모드에서 사용 가능한 도구를 다시 평가합니다.

피할 수 없는 경계가 하나 있습니다. 도구 목록과 스키마는 핫 리프레시되지만, 서버 instructions는 MCP initialize 중에 한 번만 전송되며 기존 연결에서는 교체할 수 없습니다. 변경된 지침 텍스트를 받으려면 클라이언트가 재연결/재초기화해야 합니다.

전송(Transports)

Stdio

MCP_TRANSPORT=stdio를 설정합니다. stdout은 MCP 프로토콜 전용이며 로그는 stderr로 리디렉션됩니다. stdio 배포에는 외부 FHIR_JWKS_URL을 사용하십시오.

Streamable HTTP

HTTP 전송은 상태 비저장(stateless)이며 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가 없는 준비 상태 스냅샷을 반환합니다.

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

권한 부여가 활성화되면 authz는 활성 공급자를 보고하고 tools는 등록된 도구 수가 호출자별로 다르기 때문에 생략됩니다.

HTTP를 localhost 이상으로 노출할 때는 TLS 및 사용자 인증에 역방향 프록시를 사용하십시오. 공용 인터페이스에 바인딩할 때는 ALLOWED_HOSTS를 설정하십시오.

호출자별 권한 부여(Entra, 선택 사항)

기본적으로(MCP_AUTHZ=none) 모든 호출자는 /metadata와 백엔드 SMART 범위에 의해서만 제한되는 전체 도구 집합을 볼 수 있습니다. MCP_AUTHZ=entra를 설정하면 선택적 호출자별 계층이 추가됩니다. 각 /mcp 요청은 Microsoft Entra가 발급한 Authorization: Bearer <token>을携带해야 하며, 호출자의 앱 역할(App Roles) 이 해당 요청에 대해 빌드할 도구를 결정합니다. 이는 MCP 계층 권한 부여일 뿐이며 FHIR 서버 자체의 권한 부여를 대체하지 않으며, 백엔드 SMART 토큰과 구성이 이미 허용하는 것에서 빼는 역할만 할 수 있습니다.

API 앱 등록은 매니페스트에서 requestedAccessTokenVersion을 2로 설정해야 합니다. 공급자는 테넌트별 v2 발급자를 검증하며 MCP_ENTRA_AUDIENCE가 API 애플리케이션의 클라이언트 ID일 것으로 기대합니다.

호출자에게 역할이 없는 도구는 전혀 등록되지 않습니다. 단순히 차단되는 것이 아니라 tools/list에서 아예 누락됩니다. 헬퍼 도구(capabilities, paginate, terminology_lookup, code_search)는 게이트되지 않습니다.

앱 역할 값(기본 FhirHydrant 접두사 포함):

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)를 추가하려면 두 곳만 수정하면 됩니다:

1. ts/mcp/authz/auth0.ts를 생성해 AuthzProvider를 내보냅니다 — validate(authorization)를 구현하여 { subject, roles }를 반환하게 하고(거부하려면 throw), 선택적으로 validateConfig()를 구현하여 프로바이더 환경 변수가 없으면 빠르게 실패하게 합니다. 프로바이더별 환경 변수는 모두 이 모듈 안에 유지하고 Config에 필드를 추가하지 마세요.

2. ts/mcp/authz/registry.ts에 항목 하나를 추가합니다: 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로 생성됩니다.