halaxy-mcp

Halaxy practice-management API용 MCP 서버이며, Python으로 작성되었습니다. MCP 클라이언트(Claude, GitHub Copilot 등)가 여러분의 Halaxy 계정에 연결해 "오늘 내 캘린더에 뭐가 있지?", "오늘 예약 중 아직 청구서가 발행되지 않은 것은?", "특정 보험사에 미결제된 청구서는 무엇이지?" 같은 질문에 답할 수 있게 해 줍니다.

이것은 한 진료기관이 자체적으로 사용하려고 만든 소규모 단일 테넌트(single-tenant) 도구이지, 범용 Halaxy SDK가 아닙니다. 아래의 의도적으로 구현하지 않는 것을 참고하세요.

Tools

• list_invoices(date) - 특정 날짜(기본값: 오늘)로 날짜가 찍힌 청구서를 반환합니다. 각 청구서에는 payer_name(항상 포함)과 patient 객체(지급자가 보험사/고용주가 아닌 실제 환자일 때만 포함)가 있습니다.

• list_appointments(date, appointment_type) - 특정 날짜의 예약을 반환하며, 각 항목은 "session"(실제 내원 환자 예약) 또는 "meeting"(차단, 블로커/리마인더/내부 메모 등 연결된 환자가 없는 모든 것)으로 태그됩니다. 세션에는 다음 항목도 포함됩니다.

  • session_mode - "F2F" 또는 "Telehealth". 예약이 걸린 HealthcareService에서 확인됩니다.

  • patient - id/name/initials/telecom/patient_status/is_active_client (아래 Patient 데이터 참고)

  • invoice - 한 번이라도 발행된 경우 연결된 청구서로서, Halaxy의 예약→청구서(appointment→invoice) 직접적인 참조를 통해 가져옵니다(날짜로 추측하는 것보다 신뢰성이 높으며, 코드의 주석 참고).

  • awaiting_insurer_invoice - 아직 청구서가 없고그리고 환자가 "billed to an organisation"으로 표시된 활성 Coverage를 기록으로 갖고 있는 경우에만 채워집니다. 즉 보험사/고용주에게 청구되어야 하지만 아직 청구되지 않은 세션을 나타냅니다.

  • referrals - 환자의 활성 Referral 목록(아래 list_referrals 참고)을 포함하므로, 현재 세션 사용 횟수를 추가 호출 없이 바로 알 수 있습니다.

• list_practitioners() - 임상 재직자 목록을 각각의 PractitionerRole ID와 함께 반환합니다. 클라이언트가 "오늘 Alice 일정 뭐지?" 같은 질문을 list_appointments에 대조하기 전에 역할 ID로 변환할 수 있습니다.

• list_invoices_by_payer(payer_name) - 특정 보험사/고용주/기관(예: "Acme Insurance")에 지금까지 청구된 모든 청구서를 날짜와 무관하게 반환합니다. Halaxy의 Invoice?recipient=를 직접 검색하며, list_invoices의 소급 기간 창(back-window)에 의한 사각지대가 없습니다(아래 참조).

• list_referrals(flag) - 진료에서 활성 상태인 모든 Referral을 반환합니다. Halaxy에서 GP 또는 기타 진료/의뢰가 지원 제도(funding scheme) 아래 일정 수의 세션 및/또는 금액을 허용하는 모델입니다(가장 흔하게는 Medicare Mental Health Treatment Plan - 많은 이들이 "세션 6회부터"라고 아는 것 - 외에도 DVA, WorkCover 등 포함). 각 항목은 sessions_total/sessions_used/sessions_remaining, amount_total/amount_used, 만료일, 그리고 계산된 flags: "over_limit"(사용 ≥ 승인), "expiring_soon"(30일 이내 만료), "expired"를 갖습니다. 원한다면 특수 플래그 하나로만 필터링할 수 있습니다. 예를 들어 "세션이 곧 고갈될 사람이 누구냐."

Required Halaxy API 키 스코프

필요한 스코프에 따라 Halaxy에서 API 키를 생성합니다(Settings → API Keys) . 이 서버는 권한 범위가 꺼져 있으면 우아하게 처리되며, 해당 도구를 사용할 때 그 범위에서 실패할 뿐입니다.

환자 데이터

이 서버는 환자에 대해 노출되는 정보를 의도적으로 최소화합니다. Halaxy의 Patient 리소스에는 DOB, 주소, 성별, 비상연락처, 참조 소스 메모 등도 들어 있지만, 여기서는 필요하지 않습니다. 그리고 이것은 단지 관례가 아니라 코드로 강제되고 있으며, 무엇을 요청하든 모든 환자 조회가 MCP 클라이언트에 도달하기 전에 id/name/initials/telecom/patient_status/is_active_client로 필터링됩니다(halaxy_mcp.py의 ALLOWED_PATIENT_FIELDS).

임상/세션 노트는 어떤 키나 스코프에서도 이 API으로 전혀 조회할 수 없습니다. Halaxy의 /metadata 능력 문(capabil) 에 따르면 환자 노트 리소스(DocumentReference)는 create/patch만 지원하고 읽기는 없습니다. 이는 Halaxy UI(임상 노트에 Create 토글밖에 없음)와도 동일하며, 이 서버가 노출하지 않기로 한 것이 아니라 API 자체의 제한입니다.

Referrals and session limits

Halaxy에서는 GP Mental Health Treatment Plan(및 유사한 DVA, WorkCover)을 ReferralDefinition에 연결된 Referral로 모델링합니다. ReferralDefinition은 진료의뢰 유형이며 세션/금액 상한을 전달합니다(예: 테스트 중 실제 ReferralDefinition 하나가 "Medicare: MHTP Referral"이고 문자 그대로 6회 세션 한도였습니다). sessions_remaining은 Halaxy가 직접 반환하지 않으며, 여기서는 sessions_total - sessions_used로 계산합니다.

실제 데이터에서 확인된 몇 가지 알아두면 이를잘 것:

• 한 환자는 동시에 여러 개의 활성 Referral을 가질 수 있습니다(예: 진료된 의료진마다 하나). 이 서버는 "그" 하나를 추측하지 않고 전부 반환합니다.

• 실제로는 sessions_used가 sessions_total을 초과할 수 있습니다(Medicare는 예약 시 세션 한도를 강제 또는 중단시키지 않기 때문에). 이를 위해 "over_limit" 플래그가 있는 것으로.

• 어떤 Referral은 구조화된 type/referrer가 아예 없고 자유 텍스트 comment만 있는 것입니다. 이것이 유일한 탐색일 때는 as-is 그대로 반환합니다.

• Halaxy 자체의 active 필드는 Referral의 기간이 만료되어도 자동으로 false로 바뀌지 않는 것처럼 보입니다. 따라서 "expired"/"expiring_soon" 플래그는 active를 그대로 바로 보지 않고 period.end로부터 계산합니다.

If a scope is not enabled

각 도구는 사용되는 API 키에 해당 스코프 활성화되어야 합니다(위 표 참조). 스코프가 없으면 Halaxy는 401/403 또는 OperationOutcome 오류로 응답합니다. 이 서버는 이를 "새로 0건"으로 조용히 처리하지 않고, 리소스 이름과 HTTP 상태, 그리고 Halaxy의 오류 메시지를 포함한 명확한 HalaxyPermissionError를 발생시킵니다. 이 검사이 없다면, 스코프 누락과 실제로 아무것도 없는 결과(예: "오늘은 청구 없음")가 MCP 클라이언트에게 동일하게 보이게 됩니다.

Install

Requires Python 3.10 이상.

git clone https://github.com/ryanhunt/halaxy-mcp.git
cd halaxy-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
# then edit .env with your Halaxy API key's client_id/client_secret

설치가 동작하는지 확인하는 기본 체크:

source .venv/bin/activate
python3 halaxy_mcp.py

아무 것도 출력하지 않고 그냥 대기할 텐데, 이것이 정상입니다. stdin/stdout으로 MCP 클라이언트가 들어오기를 기다리기 때문입니다. 중단으는 Ctrl+C를 누르면 됩니다.

MCP 클라이언트에 연결하기

모든 설정법은 동일한 스크립트를 로컬 하위 프로세스로 실행하고 stdio로 대화하는 방식입니다 - 네트워크 포트도, 별도 배포도 필요 없습니다. 어떤 설정이든 전체 절대 경로를 사용하세요. .venv의 Python과 halaxy_mcp.py를 가리키는.

Claude Desktop - claude_desktop_config.json에 추가하세요(macOS에서는 ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "halaxy-mcp": {
      "command": "/absolute/path/to/halaxy-mcp/.venv/bin/python3",
      "args": ["/absolute/path/to/halaxy-mcp/halaxy_mcp.py"]
    }
  }
}

앱을 완전히 종료했다가 다시 열어야 합니다(창만 닫는 것으로는 안 됩니다).

VS Code (GitHub Copilot) - 워크스페이스에 .vscode/mcp.json을 추가하세요:

{
  "servers": {
    "halaxy-mcp": {
      "type": "stdio",
      "command": "/absolute/path/to/halaxy-mcp/.venv/bin/python3",
      "args": ["/absolute/path/to/halaxy-mcp/halaxy_mcp.py"]
    }
  }
}

GitHub Copilot CLI - ~/.copilot/mcp-config.json에 추가하거나 CLI 내에서 /mcp add를 실행하세요:

{
  "mcpServers": {
    "halaxy-mcp": {
      "type": "local",
      "command": "/absolute/path/to/halaxy-mcp/.venv/bin/python3",
      "args": ["/absolute/path/to/halaxy-mcp/halaxy_mcp.py"],
      "tools": ["*"]
    }
  }
}

어느 설정에서도 env 블록은 별도로 넣지 않아도 됩니다. 스크립트가 halaxy_mcp.py 옆에 있는 자신만의 .env 파일을 로드합니다.

Known limitations, worth knowing

• list_invoices의 lookback 창에 청구서가 누락될 수 있습니다. Halaxy의 Invoice 검색에는 청구서 자체의 date 필드에 해당하는 파라미터가 없고, created/_lastUpdated만 있습니다. 따라서 list_invoices은 최근 45일간 생성된 청구서를 가져온 뒤 클라이언트에서 정확한 date와 일치하는지 필터링합니다. 보험회사/고용주에 청구되는 청구서(예: workers' comp)는 청구서에 표시된 세션 날짜보다 몇 개월 전에 생성되는 경우가 있어 이 창 범위를 벗어날 수 있습니다. list_appointments는 이 문제가 없고(appointment→invoice 연결을 직접 따라가기 때문에), list_invoices_by_payer도 없습니다(recipient 기준이며 날짜에 제한되지 않으므로). 날짜 기반의 사각지대가 중요할 때는 주로 이런 것들이입니다.

• session과 meeting 구분은 예약에 링크된 Patient 참가자가 있는지로 추론되며, Halaxy 특정 필드를 직접 사용하는 것이 아닙니다. Halaxy에서 환자 레코드를 예약에 연결하지 않고 지정된 실제 세션은 meeting으로 잘못 분류될 수 있습니다.

• 쓰기 작업(무엇든 생성/수정)은 의도적으로 구현되어 있지 않습니다.

• stdio 전송 밖에 없습니다. 원격/HTTP 변형(예: 클라우드 기반 MCP 클라이언트가 접근able 곳에서 호스팅하기 위해, 커스텀 커넥터 등)은 아직 만들어져 있지 않습니다.

What it deliberately doesn't do

이 서버는 한 치료기관의 요구에 맞는 소수의 읽기 전용 엔드포인트를 감싼 것이며, 일반적인 용도의 Halaly/FHIR 클라이언트가 아닙니다. 환자 생성/업데이트, 임상 노트, 일정 변경 또는 Halalaxy의 성격 ~50개 리소스 FHIR 표면의 대부분들을 구현하지 않았습니다. Referral 생성/수정은 지원하지 않지만, Referral 계획 추적은 위에서도 설명한 것처럼. API를 더 필요하다면, halaxy_mcp.py의 도구 함수들이 확장하기에 비교적 짧고 읽기 쉬운 서점이니 시작으로 온 것.

License

GPLv3 - LICENSE 보세요.