Guia de ligação ao servidor

O servidor MCP no iOS permite que clientes de IA e scripts na sua rede local consultem os seus dados de saúde. O HTTP (Streamable MCP) é o transporte recomendado. O iOS também suporta TCP para configurações com ponte Node.

Os clientes são executados no seu Mac ou noutros dispositivos na mesma rede e ligam-se ao endpoint apresentado no seu iPhone.

Visão geral

Transporte	Endpoint
HTTP (recomendado)	http://{LAN_IP}:9000/mcp (ou https:// quando o HTTPS está ativado)
TCP	{LAN_IP}:9000 (sem autenticação)

Substitua {LAN_IP} pelo endereço apresentado no ecrã do Servidor enquanto o servidor estiver em execução.

Casos de utilização:

• Ligar o Claude Code, Codex, Cursor ou VS Code no seu Mac aos dados de saúde do seu iPhone
• Utilizar o mcp-remote (iOS / LAN) para clientes apenas de stdio, como o Claude Desktop
• Consultar métricas e treinos a partir de scripts na sua rede local (HTTP)
• Integrações TCP através da ponte Node health-auto-export-mcp-server

Pré-requisitos

• Health Auto Export no iPhone (a app tem de permanecer em primeiro plano enquanto os clientes estiverem ligados)
• Subscrição Premium
• HTTP: token Bearer do ecrã do Servidor
• Permissão de Rede Local no iPhone
• Dispositivo cliente: mesma Wi‑Fi ou rede local do iPhone; Node.js apenas se utilizar o mcp-remote (iOS / LAN)

Iniciar o servidor

1. No iPhone, abra o Servidor através da navegação da barra lateral
2. Escolha HTTP (recomendado) ou TCP
3. Opcionalmente, ative Usar HTTPS (instruções abaixo)
4. Toque em Iniciar servidor
5. Copie o URL do endpoint e o token Bearer

O servidor para automaticamente se o Health Auto Export passar para segundo plano (tanto em HTTP como em TCP).

Autenticação (HTTP)

Todos os pedidos HTTP requerem:

Authorization: Bearer <o-seu-token>

• Regenere o token no ecrã do Servidor se considerar necessário
• Em HTTP simples, o token é enviado através de uma ligação não encriptada; utilize apenas em redes de confiança, ou ative o HTTPS
• O TCP legado não tem autenticação (sem alterações)

HTTPS (TLS)

Quando Usar HTTPS está ativado, a app gera uma Autoridade de Certificação (CA) local privada e um certificado de servidor assinado por essa CA. Os clientes têm de confiar na CA exportada antes de poderem ligar-se através de https://.

Ativar o HTTPS

1. Abra a vista do Servidor através da navegação da barra lateral
2. Ative Usar HTTPS
3. Toque em Exportar certificado CA e utilize a folha de partilha para enviar por AirDrop ou guardar o ficheiro da CA em cada dispositivo cliente
4. Inicie o servidor; confirme que o URL do endpoint muda para https://

Confiar na CA nos clientes

Confie na CA exportada no dispositivo que executa o cliente de IA (normalmente o seu Mac):

1. Exporte a CA a partir do ecrã do Servidor no iPhone
2. Abra o PEM no Acesso a Porta-chaves no Mac cliente
3. Configure Confiar → Confiar sempre

Versão mínima do Node para --use-system-ca

As pontes Node (mcp-remote) só podem utilizar NODE_OPTIONS=--use-system-ca quando o Node cumpre:

Linha do Node	Versão mínima
22.x	22.19.0
23.x	23.8.0
24.x	24.6.0
25+	qualquer

Em versões mais antigas do Node, defina NODE_EXTRA_CA_CERTS com um caminho para um PEM que o processo da ponte consiga ler. Utilizar --use-system-ca numa versão do Node não suportada impede o processo de arrancar.

Âmbito de confiança: --use-system-ca confia em todo o Porta-chaves do sistema, não apenas na CA desta app. NODE_EXTRA_CA_CERTS restringe a confiança a um único ficheiro PEM (alternativa em versões mais antigas do Node). A flag está documentada para macOS/Windows.

Tipo de cliente	Configuração
Cursor, VS Code, Claude Code, Codex	Confiança no Porta-chaves do Mac cliente; utilize o endpoint https:// do ecrã do Servidor
mcp-remote (iOS / LAN)	Confie na CA no Porta-chaves do Mac que executa o mcp-remote. O trecho utiliza NODE_OPTIONS=--use-system-ca quando o Node cumpre a versão mínima; em versões mais antigas, defina NODE_EXTRA_CA_CERTS com um caminho para um PEM legível
curl / scripts	Indique --cacert /caminho/para/mcp-ca.pem ou defina NODE_EXTRA_CA_CERTS

A impressão digital da CA é apresentada no ecrã do Servidor para que possa verificar que exportou o certificado correto.

Alterações de IP LAN no iOS

Quando o IP de rede local do seu iPhone muda, a app regenera o certificado de servidor com Subject Alternative Names atualizados e reinicia o listener HTTPS. Volte a copiar o URL do endpoint se o IP tiver mudado. O certificado da CA mantém-se igual, salvo se o regenerar desativando e voltando a ativar o HTTPS.

Exemplo de endpoint HTTPS

https://192.168.1.42:9000/mcp

Substitua o anfitrião pelo valor apresentado no ecrã do Servidor.

Versão do contrato

Versão	Nomes das ferramentas TCP	Notas
v1.1.0 (predefinida)	get_*	Recomendada para configurações novas
v1.0.0	Legada (health_metrics, …)	Atualização de compatibilidade v1.0.0 com o Claude Desktop
v0.0.1	Legada	Versão mais antiga para compatibilidade

O HTTP utiliza sempre nomes de ferramentas get_*; a versão do contrato apenas afeta os valores predefinidos do esquema.

Configuração do cliente

O ecrã do Servidor inclui trechos para copiar e colar de cada integração. Utilize o endpoint e o token aí apresentados. Verifique os formatos face à versão do seu cliente.

Todos os exemplos abaixo utilizam um endereço LAN de exemplo; substitua pelo endereço do seu iPhone apresentado no ecrã do Servidor.

Claude Code (CLI)

Execute no seu Mac (requer a CLI do Claude Code):

HTTP:

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

HTTPS (depois de exportar e confiar na CA no seu Mac):

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

Claude Code / ficheiro do projeto (.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)

O Codex liga-se diretamente via Streamable HTTP, sem necessidade de uma ponte Node.js. A configuração fica em ~/.codex/config.toml (global) ou em .codex/config.toml num diretório de projeto de confiança.

CLI (recomendado):

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 manual:

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

Exporte HAE_MCP_TOKEN com o seu token Bearer antes de iniciar o Codex. Depois de configurar, execute /mcp numa sessão do Codex para confirmar que o servidor está ligado.

Se regenerar o token Bearer no Health Auto Export, atualize HAE_MCP_TOKEN e volte a executar codex mcp add, ou remova e volte a adicionar a entrada do servidor.

mcp-remote (iOS / LAN)

Para clientes apenas de stdio (como o Claude Desktop) que não conseguem ligar-se diretamente via HTTP. Requer Node.js no Mac que executa o cliente.

1. Inicie o servidor no iPhone e copie o endpoint e o token
2. No seu Mac, selecione mcp-remote (iOS / LAN) no ecrã do Servidor e copie o trecho JSON, ou cole na configuração MCP do cliente (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 o HTTPS está ativado:

1. Exporte a CA a partir do iPhone e confie nela no Acesso a Porta-chaves (Confiar sempre) no seu Mac
2. Utilize https://192.168.1.42:9000/mcp em args
3. Quando o Node cumprir a versão mínima para --use-system-ca (22.19.0 no 22.x, 23.8.0 no 23.x, 24.6.0 no 24.x, ou qualquer versão 25+), adicione:

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

Em versões mais antigas do Node, defina NODE_EXTRA_CA_CERTS com um caminho para um PEM legível. Reinicie o cliente stdio depois de atualizar a configuração.

Reduzir a latência de arranque: o npx -y transfere o mcp-remote na primeira utilização e volta a verificar quando a cache expira, o que pode causar atrasos de vários segundos. Instalar globalmente elimina este atraso:

npm install -g mcp-remote@0.1.16

Argumentos das ferramentas

Formatos de data

Os parâmetros start e end aceitam dois formatos:

Formato	Exemplo	Notas
yyyy-MM-dd	2026-06-13	Data inicial: meia-noite; data final: 23:59:59
yyyy-MM-dd HH:mm:ss Z	2026-06-13 00:00:00 +0000	Hora explícita e desvio de fuso horário

TCP

• JSON-RPC não encriptado e sem autenticação na porta 9000
• Utilize o contrato v1.0.0 com a ponte Node health-auto-export-mcp-server para nomes de ferramentas legados
• Utilize o contrato v1.1.0 para nomes de ferramentas TCP get_* (atualize a ponte Node separadamente)

Sugestões

1. Mantenha o Health Auto Export em primeiro plano no iPhone enquanto houver clientes ligados
2. Regenere o token se suspeitar que foi exposto
3. Volte a copiar o URL do endpoint depois de o IP LAN do seu iPhone mudar

Suporte por chat

Reúna diagnósticos a partir dos registos de eventos da app em Definições → Avançado → Exportar registos de eventos. Consulte o Guia de registos de eventos da app. Partilhe o ficheiro zip gerado através do Suporte por Chat ou por email.