Azure AHDS FHIR MCP Server

Una implementación de servidor MCP para interactuar con Azure Health Data Services FHIR.

Documentación

Azure AHDS FHIR MCP Server 🚀

Una implementación de servidor del Protocolo de Contexto de Modelo (MCP) para Azure Health Data Services FHIR (Fast Healthcare Interoperability Resources). Este servicio proporciona una interfaz estandarizada para interactuar con servidores FHIR de Azure, permitiendo operaciones de datos de salud a través de herramientas MCP.

Configuración 🛠️

Instalación 📦

Requiere Python 3.13 o superior y uv.

Instala uv primero.

Configuración ⚙️

Consulta la guía de FastMCP sobre mcp.json aquí: https://gofastmcp.com/integrations/mcp-json-configuration

Flujo de credenciales de cliente (predeterminado):

Se utiliza para la autenticación de servicio a servicio
Deja USE_FAST_MCP_OAUTH_PROXY=false
Mantén HTTP_TRANSPORT=false para usar el transporte stdio
Utiliza el flujo de credenciales de cliente de Azure AD

{
    "mcpServers": {
        "fhir": {
            "type": "stdio",
            "command": "uvx",
            "args": [
                "azure-fhir-mcp-server"
            ],
            "env": {
                "fhirUrl": "https://your-fhir-server.azurehealthcareapis.com/fhir",
                "clientId": "your-client-id",
                "clientSecret": "your-client-secret",
                "tenantId": "your-tenant-id"
            }
        }
    }
}

Flujo OAuth en nombre de (On-Behalf-Of):

Crear el registro de la aplicación de Azure

El flujo OAuth en nombre de requiere una aplicación confidencial de Azure AD que represente al servidor MCP.

En el portal de Azure, ve a Microsoft Entra ID ➜ Registros de aplicaciones ➜ Nuevo registro. Dale un nombre descriptivo como FHIR-MCP-Server, establece Tipos de cuenta compatibles en Un solo inquilino y deja el URI de redirección sin configurar por ahora.
Después de crear la aplicación, captura el Application (client) ID y el Directory (tenant) ID generados para usarlos más adelante.
En Exponer una API, selecciona Establecer para el URI de ID de aplicación y acepta el valor sugerido api://{appId}. Agrega un ámbito llamado user_impersonation con la pantalla/descripción de consentimiento de administrador también establecida en user_impersonation.
En Certificados y secretos, crea un Nuevo secreto de cliente (por ejemplo, FHIR-MCP-Secret-New). Copia el valor del secreto inmediatamente; es necesario para la configuración clientSecret del servidor MCP.
En Autenticación, agrega los siguientes URI de redirección web para admitir el proxy OAuth de FastMCP:
- http://localhost:9002/auth/callback Asegúrate de que Tipo de cliente predeterminado permanezca en No para que la aplicación siga siendo confidencial.
En Permisos de API, elige Agregar un permiso ➜ API que usa mi organización, busca tu servidor FHIR de Azure Health Data Services y agrega los ámbitos delegados necesarios para tu escenario. Otorga el consentimiento de administrador para que el proxy FastMCP pueda solicitar tokens sin un mensaje interactivo.

Variables de entorno:
- Establece USE_FAST_MCP_OAUTH_PROXY=true
- Requiere HTTP_TRANSPORT=true
Inicia el servidor MCP con:

uv pip install -e .
uv run --env-file .env azure-fhir-mcp-server

Actualiza mcp.json:

{
    "mcpServers": {
        "fhir": {
            "type": "http",
            "url": "http://localhost:9002/mcp"
        }
    }
}

La siguiente es una tabla de las variables de configuración de entorno disponibles:

Variable	Descripción	Predeterminado	Requerido
`fhirUrl`	URL base del servidor FHIR de Azure (incluye `/fhir`)	-	Sí
`clientId`	ID de cliente del registro de la aplicación de Azure	-	Sí
`clientSecret`	Secreto de cliente del registro de la aplicación de Azure	-	Sí
`tenantId`	ID de inquilino de Azure AD	-	Sí
`USE_FAST_MCP_OAUTH_PROXY`	Habilita la integración del proxy OAuth de Azure de FastMCP	`false`	No
`HTTP_TRANSPORT`	Ejecuta el servidor MCP mediante transporte HTTP (requerido para el proxy OAuth)	`false`	No
`FASTMCP_HTTP_PORT`	Puerto expuesto cuando `HTTP_TRANSPORT=true`	`9002`	No
`FHIR_SCOPE`	Anula el ámbito de audiencia FHIR para el flujo OBO (separado por espacios)	`{fhirUrl}/.default`	No
`FASTMCP_SERVER_AUTH_AZURE_BASE_URL`	URL base pública de tu servidor FastMCP	`http://localhost:9002`	No
`FASTMCP_SERVER_AUTH_AZURE_REDIRECT_PATH`	Ruta de devolución de llamada OAuth añadida a la URL base	`/auth/callback`	No
`FASTMCP_SERVER_AUTH_AZURE_IDENTIFIER_URI`	URI de ID de aplicación del registro de la aplicación de Azure	`api://{clientId}`	No
`FASTMCP_SERVER_AUTH_AZURE_REQUIRED_SCOPES`	Ámbitos separados por espacios solicitados por el proveedor de Azure	`user_impersonation`	No
`FASTMCP_SERVER_AUTH_AZURE_ADDITIONAL_AUTHORIZE_SCOPES`	Ámbitos opcionales separados por espacios añadidos a la solicitud de autorización	-	No
`LOG_LEVEL`	Nivel de registro	`INFO`	No

Herramientas disponibles 🔧

Operaciones de recursos FHIR

search_fhir - Busca recursos FHIR basándose en un diccionario de parámetros de búsqueda
get_user_info - (Solo OAuth) Devuelve información sobre el usuario de Azure autenticado

Acceso a recursos

El servidor proporciona acceso a todos los recursos FHIR estándar a través del protocolo de recursos MCP:

fhir://Patient/ - Accede a todos los recursos de Patient
fhir://Patient/{id} - Accede a un recurso de Patient específico
fhir://Observation/ - Accede a todos los recursos de Observation
fhir://Observation/{id} - Accede a un recurso de Observation específico
fhir://Medication/ - Accede a todos los recursos de Medication
fhir://Medication/{id} - Accede a un recurso de Medication específico
Y muchos más...

Desarrollo 💻

Configuración de desarrollo local

1 - Clona el repositorio:

git clone https://github.com/erikhoward/azure-fhir-mcp-server.git
cd azure-fhir-mcp-server

2 - Crea y activa el entorno virtual:

Linux/macOS:

python -m venv .venv
source .venv/bin/activate

Windows:

python -m venv .venv
.venv\Scripts\activate

3 - Instala las dependencias:

pip install -e ".[dev]"

4 - Copia y configura las variables de entorno:

cp .env.example .env

Edita .env con tu configuración:

fhirUrl=https://your-fhir-server.azurehealthcareapis.com/fhir
clientId=your-client-id
clientSecret=your-client-secret
tenantId=your-tenant-id

5 - Configuración de Claude Desktop

Abre claude_desktop_config.json y agrega la siguiente configuración.

En macOS, el archivo se encuentra aquí: ~/Library/Application Support/Claude Desktop/claude_desktop_config.json.

En Windows, el archivo se encuentra aquí: %APPDATA%\Claude Desktop\claude_desktop_config.json.

{
    "mcpServers": {
        "fhir": {
            "command": "uv",
            "args": [
                "--directory",
                "/path/to/azure-fhir-mcp-server/repo",
                "run",
                "azure_fhir_mcp_server"
            ],
            "env": {
                "LOG_LEVEL": "DEBUG",
                "fhirUrl": "https://your-fhir-server.azurehealthcareapis.com/fhir",
                "clientId": "your-client-id",
                "clientSecret": "your-client-secret",
                "tenantId": "your-tenant-id"
            }
        }
    }
}

6 - Reinicia Claude Desktop.

Ejecución de pruebas

# Run all tests
python -m pytest tests/ -v

# Run with coverage
pytest tests/ --cov=src/azure_fhir_mcp_server

# Run specific test
pytest tests/test_fastmcp_metadata.py::TestFastMCPMetadata::test_fastmcp_server_discovery -v

# Run with detailed output
pytest tests/test_fastmcp_metadata.py::TestFastMCPMetadata::test_output_detailed_metadata -v -s

Contribuciones 🤝

¡Las contribuciones son bienvenidas! No dudes en enviar una solicitud de extracción (Pull Request).

Haz un fork del repositorio
Crea tu rama de características (git checkout -b feature/AmazingFeature)
Haz commit de tus cambios (git commit -m '✨ Add some AmazingFeature')
Haz push a la rama (git push origin feature/AmazingFeature)
Abre una solicitud de extracción (Pull Request)

Licencia ⚖️

Licenciado bajo MIT - consulta el archivo LICENSE.md.

Este no es un producto oficial de Microsoft o Azure.