Configure seu agente

O app lançado para Mac inclui dois auxiliares locais assinados: healthmd-mcp para ferramentas tipadas de agentes e healthmd para fluxos explícitos da CLI. A CLI multiplataforma separada com MCP direto para iPhone está empacotada publicamente como uma prévia explicitamente não qualificada; a validação de lançamento em dispositivos físicos continua obrigatória para a primeira versão estável.

O HealthKit permanece no iPhone.

A configuração dá a um cliente local acesso às interfaces limitadas do Health.md. Ela não dá ao computador ou ao agente acesso direto ao HealthKit nem envia sua base de dados de origem para uma nuvem do Health.md.

Escolha uma interface

Objetivo	Comece com	Prossiga para
Permitir que Codex ou Claude consultem e criem gráficos de dados de saúde no Mac	`healthmd-mcp` integrado por stdio	Servidor e ferramentas MCP
Exportar JSON canônico ou arquivos gerados em um script no Mac	CLI `healthmd` integrada	CLI
Conectar diretamente a um iPhone aberto sem o app para Mac	CLI direta portátil (prévia)	Acesso direto ao iPhone
Desenvolver com base em envelopes exatos de solicitação e resposta	API de loopback ou contratos públicos	API de loopback
Analisar schemas, registros, evidências ou fixtures geradas	Referência versionada	Contratos de dados

As escolhas de transporte são explícitas; a CLI autônoma nunca muda silenciosamente para o acesso pelo app para Mac.

Codex com o app para Mac

Disponível agora · auxiliar assinado para Mac

Instale o Health.md para Mac, abra a tela CLI e copie o caminho exibido do MCP integrado caso o app não esteja em /Applications.

Adicione o auxiliar assinado separado healthmd-mcp a ~/.codex/config.toml:

[mcp_servers.healthmd]
command = "/Applications/Health.md.app/Contents/Helpers/healthmd-mcp"
args = []
startup_timeout_sec = 10
tool_timeout_sec = 1200
default_tools_approval_mode = "prompt"

Reinicie o Codex, chame healthmd_doctor, resolva os IDs com healthmd_metrics, adquira explicitamente um escopo pequeno com a ferramenta de atualização e consulte-o com uma ferramenta tipada como healthmd_metric_chart. O servidor integrado disponibiliza 21 ferramentas, incluindo prontidão do Mac, tarefas persistentes de atualização de contexto criptografado, evidências e visualizações.

Claude Desktop ou Claude Code no Mac

Adicione o auxiliar integrado à configuração MCP do Claude Desktop ou a um .mcp.json confiável do Claude Code:

{
  "mcpServers": {
    "healthmd": {
      "command": "/Applications/Health.md.app/Contents/Helpers/healthmd-mcp",
      "args": []
    }
  }
}

Reinicie o cliente depois de alterar a configuração. Configurações no escopo do projeto ainda exigem confiança no workspace e aprovação explícita do servidor. Mantenha os apps do Mac e do iPhone abertos quando uma ferramenta precisar de dados recentes do HealthKit.

Qualquer cliente MCP stdio no Mac

Configure um processo local:

command: /Applications/Health.md.app/Contents/Helpers/healthmd-mcp
arguments: none
transport: stdio

O host controla stdin e o ciclo de vida do processo. Não inicie o auxiliar como um comando interativo comum nem o envolva em um shell que altere a saída JSON-RPC. Use tools/list do MCP para conhecer os schemas exatos disponibilizados pelo app instalado.

Configuração direta portátil

Prévia pública · ainda não qualificada como estável

A CLI Rust multiplataforma, healthmd setup codex, o comando healthmd mcp serve no mesmo binário e o emparelhamento direto no Linux/Windows estão empacotados publicamente como uma prévia explicitamente não qualificada.

No macOS ou Linux, instale com brew install CodyBontecou/tap/healthmd. Depois, healthmd setup codex configura o Codex de forma idempotente e inicia o emparelhamento direto com o iPhone. Use a compilação móvel exata indicada pela evidência da versão; publicar o pacote não comprova compatibilidade móvel. A página CLI direta para iPhone documenta o transporte e o protocolo.

Fluxos explícitos da CLI

Para extração canônica ou automação orientada a arquivos, invoque healthmd diretamente, em vez de pedir a um host MCP que transporte um grande corpo de origem:

healthmd status
healthmd extract --category Sleep --last 7 --output sleep.json
healthmd export --last 7 --destination "$HOME/Documents/HealthVault"

A disponibilidade e a gramática diferem entre o auxiliar integrado para Mac e a CLI multiplataforma independente. Consulte CLI do Health.md antes de copiar comandos para uma automação não supervisionada.

Emparelhamento e prontidão portáteis

Prévia · fluxos diretos portáteis

Estes são os fluxos portáteis incluídos atualmente no pacote público. O caminho do MCP integrado ao Mac continua usando a conexão existente do app para Mac com o iPhone.

Os fluxos diretos do MCP e da CLI exigem um emparelhamento confiável, feito uma única vez, com o Health.md no iPhone. O emparelhamento usa um canal autenticado e criptografado e armazenamento nativo de credenciais no macOS, Linux ou Windows.

Ative Acesso ao Direct CLI no Health.md para iPhone.
Inicie o emparelhamento com healthmd setup codex ou healthmd direct pair.
Aprove a solicitação de emparelhamento limitada no iPhone.
Mantenha o Health.md em primeiro plano ao iniciar uma consulta ou exportação.
Chame healthmd_doctor no MCP ou healthmd status na CLI portátil antes de tarefas maiores.

Consulte Acesso direto ao iPhone para saber mais sobre IP manual, Tailscale, porta, dispositivo confiável, primeiro plano e recuperação.

Limites da configuração

Uma configuração de agente local não concede:

leituras ou gravações arbitrárias no HealthKit;
acesso arbitrário ao sistema de arquivos;
URLs, comandos de shell, prompts, raízes ou amostragem arbitrários pelo MCP;
permissão para ocultar dados ausentes, cobertura, unidades, evidências ou limitações;
permissão para retomar, cancelar ou sobrescrever arquivos gerados sem a aprovação aplicável.

Para obter um resultado completo, verifique o escopo solicitado, a cobertura, o percurso, as limitações e o schema de origem — não apenas o sucesso do processo.