Azure AHDS FHIR MCP Server

Uma implementação de servidor MCP para interagir com o Azure Health Data Services FHIR.

Documentação

Azure AHDS FHIR MCP Server 🚀

Uma implementação de servidor Model Context Protocol (MCP) para Azure Health Data Services FHIR (Fast Healthcare Interoperability Resources). Este serviço fornece uma interface padronizada para interagir com servidores Azure FHIR, permitindo operações de dados de saúde por meio de ferramentas MCP.

Configuração 🛠️

Instalação 📦

Requer Python 3.13 ou superior e uv.

Instale o uv primeiro.

Configuração ⚙️

Veja as orientações do FastMCP sobre mcp.json aqui: https://gofastmcp.com/integrations/mcp-json-configuration

Fluxo de Credenciais do Cliente (padrão):

Usado para autenticação serviço a serviço
Deixe USE_FAST_MCP_OAUTH_PROXY=false
Mantenha HTTP_TRANSPORT=false para usar o transporte stdio
Usa o fluxo de credenciais do cliente do 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"
            }
        }
    }
}

Fluxo OAuth On-Behalf-Of:

Criar o Registro do Aplicativo Azure

O fluxo OAuth on-behalf-of requer um aplicativo confidencial do Azure AD que representa o servidor MCP.

No portal do Azure, vá para Microsoft Entra ID ➜ Registros de aplicativos ➜ Novo registro. Dê a ele um nome descritivo como FHIR-MCP-Server, defina Tipos de conta com suporte como Locatário único e deixe o URI de redirecionamento não definido por enquanto.
Após a criação do aplicativo, capture o Application (client) ID e o Directory (tenant) ID gerados para uso posterior.
Em Expor uma API, selecione Definir para o URI da ID do aplicativo e aceite o valor sugerido api://{appId}. Adicione um escopo chamado user_impersonation com exibição/descrição de consentimento do administrador também definida como user_impersonation.
Em Certificados e segredos, crie um Novo segredo do cliente (por exemplo, FHIR-MCP-Secret-New). Copie o valor do segredo imediatamente; ele é necessário para a configuração clientSecret do servidor MCP.
Em Autenticação, adicione os seguintes URIs de redirecionamento da Web para dar suporte ao proxy OAuth do FastMCP:
- http://localhost:9002/auth/callback Garanta que o Tipo de cliente padrão permaneça Não para que o aplicativo permaneça confidencial.
Em Permissões de API, escolha Adicionar uma permissão ➜ APIs que minha organização usa, pesquise seu servidor Azure Health Data Services FHIR e adicione os escopos delegados necessários para seu cenário. Conceda consentimento do administrador para que o proxy FastMCP possa solicitar tokens sem um prompt interativo.

Variáveis de ambiente:
- Defina USE_FAST_MCP_OAUTH_PROXY=true
- Requer HTTP_TRANSPORT=true
Inicie o servidor MCP com:

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

Atualize o mcp.json:

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

A seguir está uma tabela das variáveis de configuração de ambiente disponíveis:

Variável	Descrição	Padrão	Obrigatório
`fhirUrl`	URL base do servidor Azure FHIR (inclua `/fhir`)	-	Sim
`clientId`	ID do cliente do registro do aplicativo Azure	-	Sim
`clientSecret`	Segredo do cliente do registro do aplicativo Azure	-	Sim
`tenantId`	ID do locatário do Azure AD	-	Sim
`USE_FAST_MCP_OAUTH_PROXY`	Habilitar integração do proxy OAuth do FastMCP Azure	`false`	Não
`HTTP_TRANSPORT`	Executar o servidor MCP sobre transporte HTTP (necessário para o proxy OAuth)	`false`	Não
`FASTMCP_HTTP_PORT`	Porta exposta quando `HTTP_TRANSPORT=true`	`9002`	Não
`FHIR_SCOPE`	Substituir o escopo de audiência do FHIR para o fluxo OBO (separado por espaços)	`{fhirUrl}/.default`	Não
`FASTMCP_SERVER_AUTH_AZURE_BASE_URL`	URL base pública do seu servidor FastMCP	`http://localhost:9002`	Não
`FASTMCP_SERVER_AUTH_AZURE_REDIRECT_PATH`	Caminho de retorno de chamada OAuth anexado à URL base	`/auth/callback`	Não
`FASTMCP_SERVER_AUTH_AZURE_IDENTIFIER_URI`	URI da ID do aplicativo do registro do aplicativo Azure	`api://{clientId}`	Não
`FASTMCP_SERVER_AUTH_AZURE_REQUIRED_SCOPES`	Escopos separados por espaços solicitados pelo provedor Azure	`user_impersonation`	Não
`FASTMCP_SERVER_AUTH_AZURE_ADDITIONAL_AUTHORIZE_SCOPES`	Escopos opcionais separados por espaços adicionados à solicitação de autorização	-	Não
`LOG_LEVEL`	Nível de log	`INFO`	Não

Ferramentas Disponíveis 🔧

Operações de Recursos FHIR

search_fhir - Pesquisar recursos FHIR com base em um dicionário de parâmetros de pesquisa
get_user_info - (Somente OAuth) Retorna informações sobre o usuário autenticado do Azure

Acesso a Recursos

O servidor fornece acesso a todos os recursos FHIR padrão por meio do protocolo de recursos MCP:

fhir://Patient/ - Acessar todos os recursos de Patient
fhir://Patient/{id} - Acessar um recurso de Patient específico
fhir://Observation/ - Acessar todos os recursos de Observation
fhir://Observation/{id} - Acessar um recurso de Observation específico
fhir://Medication/ - Acessar todos os recursos de Medication
fhir://Medication/{id} - Acessar um recurso de Medication específico
E muitos outros...

Desenvolvimento 💻

Configuração de Desenvolvimento Local

1 - Clone o repositório:

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

2 - Crie e ative o ambiente virtual:

Linux/macOS:

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

Windows:

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

3 - Instale as dependências:

pip install -e ".[dev]"

4 - Copie e configure as variáveis de ambiente:

cp .env.example .env

Edite o .env com suas configurações:

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

5 - Configuração do Claude Desktop

Abra claude_desktop_config.json e adicione a seguinte configuração.

No MacOs, o arquivo está localizado aqui: ~/Library/Application Support/Claude Desktop/claude_desktop_config.json.

No Windows, o arquivo está localizado aqui: %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 - Reinicie o Claude Desktop.

Executando Testes

# 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

Contribuições 🤝

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request.

Faça um fork do repositório
Crie sua branch de recurso (git checkout -b feature/AmazingFeature)
Faça commit das suas alterações (git commit -m '✨ Add some AmazingFeature')
Envie para a branch (git push origin feature/AmazingFeature)
Abra um Pull Request

Licença ⚖️

Licenciado sob MIT - veja o arquivo LICENSE.md.

Este não é um produto oficial da Microsoft ou do Azure.