halaxy-mcp

Un servidor MCP para la API de gestión de consultas Halaxy, escrito en Python. Permite que un cliente MCP (Claude, GitHub Copilot, etc.) responda preguntas como «¿qué tengo en el calendario hoy?», «¿cuáles de las citas de hoy aún no se han facturado?» o «¿qué facturas están pendientes con una aseguradora determinada?», al comunicarse con tu propia cuenta de Halaxy.

Esta es una herramienta pequeña de un solo inquilino, creada para el uso de una única consulta, no un SDK general de Halaxy; ver Lo que deliberadamente no hace más abajo.

Herramientas

• list_invoices(date) - facturas con fecha de un día determinado (por defecto, hoy). Cada factura tiene un payer_name (siempre presente) y un objeto patient (solo presente cuando el pagador es un paciente real, no una aseguradora/empleador).

• list_appointments(date, appointment_type) - citas de un día determinado, cada una etiquetada como "session" (una cita real de cliente) o "meeting" (un bloqueo/recordatorio/nota interna: cualquier cosa sin paciente vinculado). Las sesiones también incluyen:

  • session_mode - "F2F" o "Telehealth", resuelto a partir del HealthcareService contra el que se reserva la cita

  • patient - id/name/initials/telecom/patient_status/is_active_client (ver Datos del paciente más abajo)

  • invoice - la factura vinculada, si se ha emitido alguna, a través de la referencia directa cita→factura de Halaxy (más fiable que emparejar por fecha; ver las notas en el código)

  • awaiting_insurer_invoice - se rellena solo cuando aún no hay factura y el paciente tiene un Coverage activo en el registro marcado como «facturado a una organización»; es decir, señala una sesión que se espera que se facture a una aseguradora/empleador pero aún no se ha facturado

  • referrals - las derivaciones activas del paciente (ver list_referrals más abajo), de modo que el número de sesiones actuales aparece directamente sin una segunda llamada

• list_practitioners() - personal clínico, cada uno con su ID de PractitionerRole y nombre, de modo que un cliente pueda resolver «¿qué tiene Alice hoy?» a un ID de rol antes de contrastarlo con list_appointments.

• list_invoices_by_payer(payer_name) - todas las facturas facturadas a una aseguradora/empleador/organización específica (p. ej. «Acme Insurance»), sin vincular a ninguna fecha: busca directamente en Invoice?recipient= de Halaxy, por lo que no tiene el punto ciego de la ventana retrospectiva de list_invoices (ver más abajo).

• list_referrals(flag) - todas las derivaciones activas en la consulta: el modelo de Halaxy para una derivación de médico de cabecera/otro que autoriza un número determinado de sesiones y/o importes bajo un esquema de financiación (lo más habitual es un Plan de Tratamiento de Salud Mental de Medicare, «6 sesiones para empezar», como lo conoce la mayoría; pero también DVA, WorkCover, etc.). Cada una incluye sessions_total/sessions_used/sessions_remaining, amount_total/amount_used, vencimiento y flags calculados: "over_limit" (usadas ≥ autorizadas), "expiring_soon" (termina dentro de 30 días), "expired". Opcionalmente, se puede filtrar por una sola flag, p. ej. «a quién le quedan pocas sesiones».

Alcances de clave de API Halaxy necesarios

Crea una clave de API en Halaxy (Settings → API Keys) con los que necesites de entre estos: el servidor se degrada con elegancia si un alcance está desactivado; simplemente fallará en las herramientas que lo necesiten.

Ejemplo de cómo se ve esto en la propia pantalla de alcances de clave de API de Halaxy:

Datos del paciente

Este servidor minimiza deliberadamente lo que expone sobre un paciente. El recurso Patient de Halaxy también contiene fecha de nacimiento, dirección, sexo, contacto de emergencia y notas de origen de la derivación; nada de eso es necesario aquí, y está impuesto en el código (ALLOWED_PATIENT_FIELDS en halaxy_mcp.py), no solo por convención: cada búsqueda de paciente se filtra hasta id/name/initials/telecom/patient_status/is_active_client antes de que pueda llegar al cliente MCP, independientemente de lo que se pida.

Las notas clínicas/de sesión no se pueden recuperar en absoluto a través de esta API, con ninguna clave ni alcance. La declaración de capacidades /metadata de Halaxy muestra que su recurso de notas clínicas (DocumentReference) solo admite create/patch, sin lectura, lo que coincide con lo que la propia interfaz de Halaxy muestra (Clinical Notes solo tiene un interruptor Create). Es una limitación de toda la API, no algo que este servidor elija no exponer.

Derivaciones y límites de sesiones

Halaxy modela un Plan de Tratamiento de Salud Mental de un médico de cabecera (y similares: DVA, WorkCover) como una Referral vinculada a una ReferralDefinition (el tipo de derivación, que contiene el límite de sesiones/importe; p. ej., una ReferralDefinition real en las pruebas se llamaba literalmente «Medicare: MHTP Referral» con un límite de 6 sesiones). sessions_remaining no lo devuelve Halaxy directamente; aquí se calcula como sessions_total - sessions_used.

Algunas cosas confirmadas con datos reales, que conviene saber si amplías esto más adelante:

• Un paciente puede tener más de una Referral simultáneamente activa (p. ej., una por profesional al que se deriva); este servidor no intenta adivinar «la» correcta; devuelve todas.

• sessions_used puede superar a sessions_total en la práctica (Medicare no detiene de forma tajante las reservas al alcanzar el límite); para eso está la marca "over_limit".

• Algunos registros de Referral no tienen ningún tipo/remitente estructurado, solo un comment de texto libre; se muestra tal cual cuando es la única pista disponible.

• El campo active de Halaxy en una Referral no parece cambiar automáticamente a false cuando su período caduca; las marcas "expired"/"expiring_soon" se calculan a partir de period.end, no se leen de active.

Si un alcance no está habilitado

Cada herramienta necesita que su alcance correspondiente esté activado para la clave de API que está usando (ver la tabla anterior). Si falta un alcance, Halaxy responde con un 401/403 o un error OperationOutcome; el servidor lanza un HalaxyPermissionError claro (indicando el recurso, el estado HTTP y el texto de error propio de Halaxy) en lugar de tratar silenciosamente eso como «cero resultados». Sin esta comprobación, un alcance faltante y un resultado genuinamente vacío (p. ej., «no hay facturas hoy») parecerían idénticos al cliente MCP.

Instalación

Requiere 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

Comprueba que funciona:

source .venv/bin/activate
python3 halaxy_mcp.py

No imprimirá nada y simplemente se quedará ahí; es lo correcto, está esperando a que un cliente MCP se comunique con él a través de stdin/stdout. Ctrl+C para detenerlo.

Cómo conectarlo a un cliente MCP

Todos estos métodos lanzan el mismo script como subproceso local y se comunican con él a través de stdio: sin puerto de red, sin despliegue aparte. Usa la ruta completa y absoluta del Python de .venv y de halaxy_mcp.py en todos los casos.

Claude Desktop - añádelo a claude_desktop_config.json (~/Library/Application Support/Claude/claude_desktop_config.json en macOS):

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

Sal por completo de la aplicación y vuelve a abrirla después (no basta con cerrar la ventana).

VS Code (GitHub Copilot) - añade .vscode/mcp.json en un área de trabajo:

{
  "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 - añádelo a ~/.copilot/mcp-config.json (o ejecuta /mcp add dentro de la CLI):

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

No se necesita ningún bloque env en ninguno de estos casos: el script carga su propio archivo .env desde la misma carpeta en la que está halaxy_mcp.py.

Limitaciones conocidas que conviene tener en cuenta

• La ventana retrospectiva de list_invoices puede omitir facturas. La búsqueda de Invoice de Halaxy no tiene ningún parámetro para el campo date propio de la factura, solo created/_lastUpdated; por eso list_invoices obtiene las facturas creadas en los últimos 45 días y filtra en el lado del cliente una coincidencia exacta de date. Las facturas pagaderas por aseguradora/empleador (p. ej., compensación laboral) a veces se crean meses antes de la sesión a la que finalmente se les asigna fecha, lo que puede quedar fuera de esa ventana. list_appointments no tiene este problema (sigue el enlace cita→factura directamente), y list_invoices_by_payer tampoco (busca por destinatario, sin límite de fecha): prefiere estas cuando el punto ciego basado en la fecha importe.

• session frente a meeting se deduce de si la cita tiene un participante Patient vinculado, no de ningún campo explícito de Halaxy: una sesión real reservada sin vincular un registro de paciente en Halaxy se clasificaría erróneamente como reunión.

• No se implementan operaciones de escritura (crear/actualizar nada), a propósito.

• Solo transporte stdio: todavía no está creada una variante remota/HTTP (para alojar esto en algún lugar accesible por un cliente MCP basado en la nube, p. ej., un conector personalizado).

Lo que deliberadamente no hace

Esto envuelve un puñado de endpoints de solo lectura que se ajustan a las necesidades de una única consulta, no un cliente general de Halaxy/FHIR. No implementa creación/actualización de pacientes, notas clínicas, cambios de agenda ni la mayor parte de la superficie FHIR de Halaxy de ~50 recursos (el seguimiento de derivaciones está cubierto, ver arriba, pero no la creación/actualización de derivaciones). Si necesitas más de la API, las funciones de herramienta en halaxy_mcp.py son un punto de partida razonablemente corto y legible para ampliarlo.

Licencia

GPLv3 - ver LICENSE.