Configura il tuo agente

L’app per Mac distribuita include due helper locali firmati: healthmd-mcp per strumenti tipizzati destinati agli agenti e healthmd per flussi di lavoro CLI espliciti. La CLI multipiattaforma separata con MCP diretto per iPhone è distribuita pubblicamente come anteprima esplicitamente non qualificata; i test di rilascio su dispositivi fisici restano obbligatori per la prima versione stabile.

HealthKit rimane su iPhone.

La configurazione consente a un client locale di accedere alle interfacce con ambito limitato di Health.md. Non concede al computer o all'agente l'accesso diretto a HealthKit e non carica la libreria di origine su un cloud di Health.md.

Scegli un’interfaccia

Obiettivo	Inizia con	Prosegui con
Consentire a Codex o Claude di interrogare e rappresentare graficamente i dati sanitari su Mac	`healthmd-mcp` incluso tramite stdio	Server e strumenti MCP
Esportare JSON canonico o file generati in uno script per Mac	CLI `healthmd` inclusa	CLI
Connettersi direttamente a un iPhone aperto senza l’app per Mac	CLI diretta multipiattaforma (anteprima)	Accesso diretto a iPhone
Sviluppare usando le esatte strutture di richiesta e risposta	API loopback o contratti pubblici	API loopback
Analizzare schemi, record, evidenze o fixture generate	Riferimento con versionamento	Contratti dei dati

Le scelte relative al trasporto sono esplicite; la CLI autonoma non passa mai automaticamente all’accesso tramite l’app per Mac.

Codex con l’app per Mac

Disponibile ora · helper firmato per Mac

Installa Health.md per Mac, apri la schermata CLI e copia il percorso MCP incluso visualizzato se l'app non si trova in /Applications.

Aggiungi l’helper firmato separato 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"

Riavvia Codex, chiama healthmd_doctor, risolvi gli ID con healthmd_metrics, acquisisci esplicitamente un piccolo ambito con lo strumento di aggiornamento e interrogalo con uno strumento tipizzato come healthmd_metric_chart. Il server incluso espone 21 strumenti, tra cui verifica dell’idoneità del Mac, processi di aggiornamento del contesto crittografato, evidenze e visualizzazioni.

Claude Desktop o Claude Code su Mac

Aggiungi l’helper incluso alla configurazione MCP di Claude Desktop o a un file .mcp.json attendibile di Claude Code:

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

Riavvia il client dopo averne modificato la configurazione. Le configurazioni definite a livello di progetto richiedono comunque che l’area di lavoro sia considerata attendibile e che il server venga approvato esplicitamente. Mantieni aperte le app per Mac e iPhone quando uno strumento richiede dati HealthKit aggiornati.

Qualsiasi client MCP stdio su Mac

Configura un processo locale:

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

L’host gestisce stdin e il ciclo di vita del processo. Non avviare l’helper come un normale comando interattivo e non racchiuderlo in una shell che modifichi l’output JSON-RPC. Usa tools/list di MCP per individuare gli schemi esatti esposti dall’app installata.

Configurazione diretta multipiattaforma

Anteprima pubblica · non ancora qualificata come stabile

La CLI Rust multipiattaforma, healthmd setup codex, il comando healthmd mcp serve eseguito dallo stesso binario e l'abbinamento diretto su Linux/Windows sono distribuiti pubblicamente come anteprima esplicitamente non qualificata.

Su macOS o Linux, installa con brew install CodyBontecou/tap/healthmd. Quindi healthmd setup codex configura Codex in modo idempotente e avvia l’abbinamento diretto con iPhone. Usa la build mobile esatta indicata dalle prove di rilascio; la pubblicazione del pacchetto non dimostra la compatibilità mobile. La pagina CLI diretta per iPhone documenta il trasporto e il protocollo.

Flussi di lavoro CLI espliciti

Per l’estrazione canonica o l’automazione orientata ai file, invoca direttamente healthmd invece di chiedere a un host MCP di trasferire un corpo di origine di grandi dimensioni:

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

La disponibilità e la sintassi differiscono tra l’helper incluso per Mac e la CLI multipiattaforma autonoma. Consulta CLI di Health.md prima di copiare i comandi in automazioni non presidiate.

Abbinamento multipiattaforma e idoneità operativa

Anteprima · flussi di lavoro diretti multipiattaforma

Questi sono i flussi portatili attualmente inclusi nel pacchetto pubblico. Il percorso MCP integrato per Mac continua a usare la connessione esistente dell’app per Mac con iPhone.

I flussi di lavoro MCP e CLI diretti richiedono un abbinamento attendibile, da eseguire una sola volta, con Health.md su iPhone. L’abbinamento usa un canale crittografato e autenticato e l’archiviazione nativa delle credenziali su macOS, Linux o Windows.

Abilita Accesso CLI diretto in Health.md su iPhone.
Avvia l’abbinamento da healthmd setup codex o healthmd direct pair.
Approva la richiesta di abbinamento con ambito limitato su iPhone.
Mantieni Health.md in primo piano mentre avvii una query o un’esportazione.
Chiama healthmd_doctor in MCP o healthmd status nella CLI multipiattaforma prima di operazioni più complesse.

Consulta Accesso diretto a iPhone per informazioni su IP manuale, Tailscale, porta, dispositivo attendibile, esecuzione in primo piano e procedure di ripristino.

Limiti della configurazione

La configurazione di un agente locale non concede:

letture o scritture arbitrarie in HealthKit;
accesso arbitrario al file system;
URL, comandi shell, prompt, radici o campionamento arbitrari tramite MCP;
l’autorizzazione a nascondere dati mancanti, copertura, unità, evidenze o limitazioni;
l’autorizzazione a riprendere, annullare o sovrascrivere file generati senza l’approvazione applicabile.

Per ottenere un risultato completo, esamina l’ambito richiesto, la copertura, l’attraversamento, le limitazioni e lo schema di origine, non soltanto il completamento del processo.