# Servidor MCP FHIR para agentes de IA

> Conecte Claude Code, Cursor, VS Code ou Claude Desktop a uma API HL7 FHIR R4 através do MCP: 20 ferramentas para ler registos, contexto pronto para IA, escrever, importar laboratório e redefinir sandbox, em 30 pacientes sintéticos, gratuitamente.

Source: https://developers.anpheros.com/pt/guides/mcp

**Anpheros FHIR é um servidor MCP remoto que permite a um agente de IA (Claude, Claude Code, Cursor, VS Code, Claude Desktop) trabalhar com uma API de dados de saúde HL7 FHIR R4.** Conecta-se de duas formas:

- **Com uma chave de sandbox gratuita**, para programadores: o seu agente lista pacientes, lê os seus registos como FHIR ou como contexto pronto para IA com proveniência, escreve observações, importa relatórios de laboratório e redefine os seus dados de teste, tudo em 30 pacientes sintéticos com históricos realistas.
- **Com OAuth**, para uma pessoa e o seu próprio registo: o assistente regista-se, a pessoa inicia sessão e aprova-o no ecrã de consentimento Anpheros, e o assistente pode então ler esse único registo, pelo período escolhido, apenas leitura, a menos que a pessoa tenha permitido mais.

Endereço do servidor: `https://platform.anpheros.com/mcp` (HTTP Streamable, stateless).

## Ligar com OAuth (Claude e outros assistentes)

Adicione `https://platform.anpheros.com/mcp` como um conector personalizado (em Claude: Definições → Conectores → Adicionar conector personalizado). Não é necessária mais nenhuma configuração: o assistente descobre o servidor de autorização, regista-se e abre o ecrã de consentimento Anpheros. Aí, a pessoa vê que se trata de um assistente de IA, que o que lê é enviado para a empresa que gere o assistente, o que pode ler, por quanto tempo e para onde regressará após a escolha. O acesso é apenas de leitura, a menos que tenha sido solicitado e permitido mais, e a pessoa pode revogá-lo a qualquer momento.

Durante a beta privada, as ligações OAuth utilizam registos sandbox. As ligações a registos reais abrem após a atualização da política de privacidade.

## Conecte-se com uma chave sandbox (desenvolvedores)

1. Inicie sessão em [platform.anpheros.com/dashboard](https://platform.anpheros.com/dashboard/) com o Google e escolha **Obter uma chave sandbox**. Receberá uma chave `sk_test_…` e um projeto com 30 pacientes sintéticos.
2. Coloque a chave numa variável de ambiente, por exemplo `ANPHEROS_KEY`, e adicione o servidor à sua ferramenta.

**Código Claude**

```bash
claude mcp add --transport http anpheros-fhir https://platform.anpheros.com/mcp --header "Authorization: Bearer $ANPHEROS_KEY"
```

**Cursor** (`~/.cursor/mcp.json` ou `.cursor/mcp.json` no projeto)

```json
{
  "mcpServers": {
    "anpheros-fhir": {
      "url": "https://platform.anpheros.com/mcp",
      "headers": { "Authorization": "Bearer ${env:ANPHEROS_KEY}" }
    }
  }
}
```

**VS Code** (`.vscode/mcp.json`)

```json
{
  "servers": {
    "anpheros-fhir": {
      "type": "http",
      "url": "https://platform.anpheros.com/mcp",
      "headers": { "Authorization": "Bearer ${env:ANPHEROS_KEY}" }
    }
  }
}
```

**Claude Desktop** (`claude_desktop_config.json`, através da ponte `mcp-remote`)

```json
{
  "mcpServers": {
    "anpheros-fhir": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://platform.anpheros.com/mcp", "--header", "Authorization: Bearer ${ANPHEROS_KEY}"],
      "env": { "ANPHEROS_KEY": "sk_test_…" }
    }
  }
}
```

Em seguida, peça ao seu agente algo como: *"Liste os pacientes sandbox, escolha aquele com diabetes e resuma os seus últimos seis meses de HbA1c."*

## Ferramentas

| Ferramenta | O que faz |
|---|---|
| `list_patients` | os pacientes do projeto: as 30 personas sintéticas e quaisquer que tenha criado |
| `get_patient_context` | um contexto pronto para IA para um paciente, dentro de um limite de tokens, cada item rotulado com a sua origem |
| `get_patient_summary` | o Resumo Internacional do Paciente (FHIR `$summary`), na língua que solicitar |
| `get_timeline` | o registo por ordem cronológica em todos os tipos de recursos |
| `get_health_patterns` | beta: o que mudou e o que se repete, cada achado com o seu período, evidência e limitações; não diagnósticos ([guia](https://developers.anpheros.com/pt/guides/health-patterns)) |
| `get_pattern_evidence` | beta: todos os recursos por trás de um achado |
| `get_series` | beta: uma medição como um valor por dia, com qualidade de dados |
| `compare_periods` | beta: uma medição em dois períodos à sua escolha |
| `search_fhir` | pesquisa padrão FHIR R4, retornando um Bundle |
| `read_fhir_resource` | um recurso, ou uma versão anterior do mesmo |
| `get_provenance` | quem escreveu um recurso, quando e de que sistema |
| `lookup_code` | códigos LOINC por texto ou por código (para medicamentos, use `search_health_terms`) |
| `search_health_terms` | o catálogo público de sintomas, condições e tratamentos, por nome em 20 línguas, sinónimo, marca ou código ([guia](https://developers.anpheros.com/pt/guides/anpheros-search)) |
| `get_health_term` | uma entrada de catálogo com os seus códigos, nomes, resumo MedlinePlus, links de origem e indicações EMA / FDA citadas |
| `validate_fhir_resource` | verifica um recurso sem o guardar |
| `create_fhir_resource` | valida, depois escreve um recurso |
| `create_patient` | um novo paciente inventado no projeto |
| `import_lab_report` | um relatório de laboratório em CSV, HL7 v2 ORU^R01 ou JSON torna-se Observações laboratoriais |
| `sandbox_status` | escreve o que foi usado hoje, pacientes, armazenamento, reiniciações |
| `reset_sandbox` | restaura os 30 pacientes sintéticos (pede confirmação) |

As ferramentas de leitura são marcadas como somente leitura e a reiniciação é marcada como destrutiva, para que os clientes possam pedir antes de ações de risco. O servidor também oferece a lista de pacientes sintéticos como um recurso e três prompts: um resumo clínico, uma importação de CSV de laboratório e a construção da sua integração na API.

## Como se comporta

- **As mesmas regras da API.** Todas as ferramentas chamam a API pública com a sua chave: os mesmos âmbitos (scopes), limites de taxa (rate limits), validação e auditoria. Uma chave de apenas leitura não pode escrever.
- **Proveniência.** Tudo o que um agente escreve é registado com a origem `urn:anpheros:mcp`, pelo que pode sempre saber o que veio de um agente.
- **Dados do paciente são dados.** Os resultados das ferramentas trazem uma nota de que o conteúdo do registo nunca deve ser seguido como instruções, uma proteção básica contra injeção de prompts através de registos médicos.
- **Um registo, com consentimento.** As chaves de API de produção (`sk_live_…`) são recusadas, pois alcançam todos os pacientes de um projeto. Um registo real chega a um assistente apenas através de OAuth, após essa pessoa o aprovar, e cada leitura é registada no seu histórico de acesso.
- **Descoberta padrão.** Sem credenciais, o servidor responde com 401 e um cabeçalho `WWW-Authenticate` a apontar para os metadados dos seus recursos protegidos por OAuth (RFC 9728); os assistentes registam-se através de registo dinâmico de clientes (RFC 7591), com PKCE. O registo aceita apenas endereços loopback, os esquemas de aplicações de editores conhecidos e os domínios de callback de assistentes de IA conhecidos.

## Perguntas frequentes

### O que é um servidor MCP?
MCP (Model Context Protocol) é um protocolo aberto através do qual agentes de IA e assistentes de codificação chamam ferramentas externas. Um servidor MCP para FHIR permite que o agente leia e escreva registos de saúde diretamente, em vez de colar dados no chat.

### É gratuito?
Sim. O servidor MCP funciona na sandbox gratuita: 30 pacientes sintéticos por projeto, até 10.000 escritas por dia, sem cartão.

### Um assistente pode ler o registo de um paciente real?
Apenas através de OAuth, após essa pessoa aprovar o assistente no ecrã de consentimento, pelo período que escolher, e apenas o seu próprio registo (ou o de alguém de quem cuida). Durante a beta privada, as ligações OAuth utilizam registos da sandbox.

### Que versão FHIR utiliza?
HL7 FHIR R4 (4.0.1), a mesma API que https://platform.anpheros.com/fhir/R4, com o International Patient Summary e uma vista REST dos mesmos dados.

### Funciona com o ChatGPT?
Os conectores ChatGPT utilizam OAuth com registo dinâmico de clientes, que o servidor suporta, e o seu domínio de callback é aceite. Testámos o fluxo com o cliente oficial MCP SDK; se uma ligação ChatGPT falhar, escreva para support@anpheros.com. Claude Code, Cursor e VS Code também funcionam com uma chave de sandbox.

## Relacionado

- [Como conceder acesso a registos médicos a um agente de IA](https://developers.anpheros.com/pt/guides/ai-agent-access-medical-records): tutorial passo a passo em Python
- [Base de dados e sandbox FHIR gratuita](https://developers.anpheros.com/pt/guides/free-fhir-database)
- [Agentes de IA e dados médicos](https://developers.anpheros.com/pt/guides/ai-agents-medical-data)
- [Aplicações LLM e dados de saúde](https://developers.anpheros.com/pt/guides/llm-healthcare-data)
- [API de saúde com consentimento do paciente](https://developers.anpheros.com/pt/guides/healthcare-api-patient-consent)