Guida alla connessione al server

Il server MCP su iOS consente a client IA e script sulla tua rete locale di interrogare i tuoi dati sulla salute. HTTP (Streamable MCP) è il trasporto consigliato. iOS supporta anche TCP per configurazioni con bridge Node.

I client vengono eseguiti sul tuo Mac o su altri dispositivi nella stessa rete e si connettono all'endpoint mostrato sul tuo iPhone.

Panoramica

Trasporto	Endpoint
HTTP (consigliato)	http://{LAN_IP}:9000/mcp (oppure https:// quando HTTPS è attivo)
TCP	{LAN_IP}:9000 (non autenticato)

Sostituisci {LAN_IP} con l'indirizzo mostrato nella schermata Server mentre il server è in esecuzione.

Casi d'uso:

• Collegare Claude Code, Codex, Cursor o VS Code sul tuo Mac ai dati sulla salute del tuo iPhone
• Usare mcp-remote (iOS / LAN) per client solo stdio come Claude Desktop
• Interrogare metriche e allenamenti da script sulla tua rete locale (HTTP)
• Integrazioni TCP tramite il bridge Node health-auto-export-mcp-server

Requisiti

• Health Auto Export su iPhone (l'app deve rimanere in primo piano mentre i client sono connessi)
• Abbonamento Premium
• HTTP: token Bearer dalla schermata Server
• Autorizzazione Rete locale sull'iPhone
• Dispositivo client: stesso Wi-Fi o LAN dell'iPhone; Node.js solo se usi mcp-remote (iOS / LAN)

Avvio del server

1. Sull'iPhone, apri Server dalla navigazione della barra laterale
2. Scegli HTTP (consigliato) o TCP
3. Attiva facoltativamente Usa HTTPS (istruzioni di seguito)
4. Tocca Avvia server
5. Copia l'URL dell'endpoint e il token Bearer

Il server si ferma automaticamente se Health Auto Export passa in background (sia per HTTP che per TCP).

Autenticazione (HTTP)

Tutte le richieste HTTP richiedono:

Authorization: Bearer <your-token>

• Rigenera il token dalla schermata Server se lo ritieni necessario
• Su HTTP semplice, il token viene inviato su una connessione non cifrata: usalo solo su reti attendibili, oppure attiva HTTPS
• Il TCP legacy non ha autenticazione (invariato)

HTTPS (TLS)

Quando Usa HTTPS è attivo, l'app genera una Certificate Authority (CA) locale privata e un certificato server firmato da tale CA. I client devono fidarsi della CA esportata prima di potersi connettere tramite https://.

Attivazione di HTTPS

1. Apri la vista Server dalla navigazione della barra laterale
2. Attiva Usa HTTPS
3. Tocca Esporta certificato CA e usa il foglio di condivisione per inviare tramite AirDrop o salvare il file CA su ogni dispositivo client
4. Avvia il server: verifica che l'URL dell'endpoint passi a https://

Fidarsi della CA sui client

Fidati della CA esportata sul dispositivo che esegue il client IA (di solito il tuo Mac):

1. Esporta la CA dalla schermata Server sull'iPhone
2. Apri il file PEM in Keychain Access sul Mac client
3. Imposta Trust → Always Trust

Versione minima di Node per --use-system-ca

I bridge Node (mcp-remote) possono usare NODE_OPTIONS=--use-system-ca solo quando Node soddisfa almeno:

Ramo Node	Versione minima
22.x	22.19.0
23.x	23.8.0
24.x	24.6.0
25+	qualsiasi

Su versioni di Node più vecchie, imposta invece NODE_EXTRA_CA_CERTS con un percorso PEM leggibile dal processo del bridge. Usare --use-system-ca su una versione di Node non supportata impedisce l'avvio del processo.

Ambito di fiducia: --use-system-ca si fida dell'intero Keychain di sistema, non solo della CA di questa app. NODE_EXTRA_CA_CERTS limita la fiducia a un singolo file PEM (soluzione alternativa su Node più vecchio). Il flag è documentato per macOS/Windows.

Tipo di client	Configurazione
Cursor, VS Code, Claude Code, Codex	Fiducia Keychain sul Mac client — usa l'endpoint https:// dalla schermata Server
mcp-remote (iOS / LAN)	Fidati della CA nel Keychain sul Mac che esegue mcp-remote. Lo snippet usa NODE_OPTIONS=--use-system-ca quando Node soddisfa la versione minima; su Node più vecchio imposta NODE_EXTRA_CA_CERTS con un percorso PEM leggibile
curl / script	Passa --cacert /path/to/mcp-ca.pem oppure imposta NODE_EXTRA_CA_CERTS

L'impronta digitale della CA è mostrata nella schermata Server, così puoi verificare di aver esportato il certificato corretto.

Cambi dell'IP LAN su iOS

Quando l'IP LAN del tuo iPhone cambia, l'app rigenera il certificato leaf con Subject Alternative Names aggiornati e riavvia il listener HTTPS. Copia nuovamente l'URL dell'endpoint se l'IP è cambiato. Il certificato CA rimane lo stesso, a meno che non lo rigeneri disattivando e riattivando HTTPS.

Esempio di endpoint HTTPS

https://192.168.1.42:9000/mcp

Sostituisci l'host con il valore mostrato nella schermata Server.

Versione del contratto

Versione	Nomi tool TCP	Note
v1.1.0 (predefinita)	get_*	Consigliata per nuove configurazioni
v1.0.0	Legacy (health_metrics, …)	Aggiornamento di compatibilità v1.0.0 per Claude Desktop
v0.0.1	Legacy	Compatibilità più vecchia

HTTP usa sempre i nomi tool get_*; la versione del contratto influisce solo sugli schemi predefiniti.

Configurazione del client

La schermata Server include snippet copia-incolla per ogni integrazione. Usa l'endpoint e il token mostrati lì. Verifica i formati in base alla versione del tuo client.

Tutti gli esempi seguenti usano un indirizzo LAN segnaposto: sostituiscilo con l'indirizzo del tuo iPhone dalla schermata Server.

Claude Code (CLI)

Da eseguire sul tuo Mac (richiede la CLI di Claude Code):

HTTP:

claude mcp add --transport http health-auto-export \
  http://192.168.1.42:9000/mcp \
  --header "Authorization: Bearer <token>"

HTTPS (dopo aver esportato e reso attendibile la CA sul tuo Mac):

claude mcp add --transport http health-auto-export \
  https://192.168.1.42:9000/mcp \
  --header "Authorization: Bearer <token>"

Claude Code / file di progetto (.mcp.json)

{
  "mcpServers": {
    "health-auto-export": {
      "type": "http",
      "url": "http://192.168.1.42:9000/mcp",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}

Cursor (~/.cursor/mcp.json)

{
  "mcpServers": {
    "health-auto-export": {
      "url": "http://192.168.1.42:9000/mcp",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}

VS Code (.vscode/mcp.json)

{
  "servers": {
    "health-auto-export": {
      "type": "http",
      "url": "http://192.168.1.42:9000/mcp",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}

Codex CLI (~/.codex/config.toml)

Codex si connette direttamente tramite Streamable HTTP: non è necessario alcun bridge Node.js. La configurazione si trova in ~/.codex/config.toml (globale) o in .codex/config.toml all'interno di una directory di progetto attendibile.

CLI (consigliata):

export HAE_MCP_TOKEN="<token>"
codex mcp add health-auto-export \
  --url http://192.168.1.42:9000/mcp \
  --bearer-token-env-var HAE_MCP_TOKEN

config.toml manuale:

[mcp_servers.health-auto-export]
url = "http://192.168.1.42:9000/mcp"
bearer_token_env_var = "HAE_MCP_TOKEN"
enabled = true

Esporta HAE_MCP_TOKEN con il tuo token Bearer prima di avviare Codex. Dopo la configurazione, esegui /mcp all'interno di una sessione Codex per verificare che il server sia connesso.

Se rigeneri il token Bearer in Health Auto Export, aggiorna HAE_MCP_TOKEN ed esegui nuovamente codex mcp add, oppure rimuovi e riaggiungi la voce del server.

mcp-remote (iOS / LAN)

Per client solo stdio (come Claude Desktop) che non possono connettersi direttamente tramite HTTP. Richiede Node.js sul Mac che esegue il client.

1. Avvia il server sull'iPhone e copia l'endpoint e il token
2. Sul tuo Mac, seleziona mcp-remote (iOS / LAN) nella schermata Server e copia lo snippet JSON, oppure incolla quanto segue nella configurazione MCP del client (Claude Desktop → Settings → Developer → Edit Config):

{
  "command": "npx",
  "args": [
    "-y",
    "mcp-remote@0.1.16",
    "http://192.168.1.42:9000/mcp",
    "--transport",
    "http-only",
    "--header",
    "Authorization: Bearer <token>"
  ]
}

Quando HTTPS è attivo:

1. Esporta la CA dall'iPhone e rendila attendibile in Keychain Access (Always Trust) sul tuo Mac
2. Usa https://192.168.1.42:9000/mcp in args
3. Quando Node soddisfa la versione minima per --use-system-ca (22.19.0 su 22.x, 23.8.0 su 23.x, 24.6.0 su 24.x, o qualsiasi versione 25+), aggiungi:

"env": {
  "NODE_OPTIONS": "--use-system-ca"
}

Su versioni di Node più vecchie, imposta invece NODE_EXTRA_CA_CERTS con un percorso PEM leggibile. Riavvia il client stdio dopo aver aggiornato la configurazione.

Riduzione della latenza di avvio: npx -y scarica mcp-remote al primo utilizzo e lo riverifica alla scadenza della cache, il che può causare ritardi di diversi secondi. Preinstallarlo globalmente elimina questo problema:

npm install -g mcp-remote@0.1.16

Argomenti dei tool

Formati data

I parametri start e end accettano due formati:

Formato	Esempio	Note
yyyy-MM-dd	2026-06-13	Data di inizio: mezzanotte; data di fine: 23:59:59
yyyy-MM-dd HH:mm:ss Z	2026-06-13 00:00:00 +0000	Orario esplicito e offset del fuso orario

TCP

• JSON-RPC non cifrato e non autenticato sulla porta 9000
• Usa il contratto v1.0.0 con il bridge Node health-auto-export-mcp-server per i nomi tool legacy
• Usa il contratto v1.1.0 per i nomi tool TCP get_* (aggiorna il bridge Node separatamente)

Suggerimenti

1. Mantieni Health Auto Export in primo piano sull'iPhone mentre i client sono connessi
2. Rigenera il token se sospetti che sia stato esposto
3. Copia nuovamente l'URL dell'endpoint dopo un cambio dell'IP LAN del tuo iPhone

Assistenza via chat

Raccogli i dati diagnostici dai log degli eventi dell'app andando su Impostazioni → Avanzate → Esporta log eventi. Consulta la Guida ai log degli eventi dell'app. Condividi il file zip generato tramite l'assistenza via chat o via email.