Guia de conexão com o servidor

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

Os clientes são executados no seu Mac ou em outros dispositivos da mesma rede e se conectam ao endpoint exibido 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 exibido na tela do Servidor enquanto o servidor estiver em execução.

Casos de uso:

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

Pré-requisitos

• Health Auto Export no iPhone (o app deve permanecer em primeiro plano enquanto houver clientes conectados)
• Assinatura Premium
• HTTP: token Bearer da tela do Servidor
• Permissão de Rede Local no iPhone
• Dispositivo cliente: mesma Wi‑Fi ou rede local do iPhone; Node.js apenas se você usar o mcp-remote (iOS / LAN)

Iniciando o servidor

1. No iPhone, abra o Servidor pela 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 a URL do endpoint e o token Bearer

O servidor é interrompido automaticamente se o Health Auto Export for para segundo plano (tanto no HTTP quanto no TCP).

Autenticação (HTTP)

Todas as solicitações HTTP exigem:

Authorization: Bearer <seu-token>

• Gere um novo token na tela do Servidor se julgar necessário
• No HTTP simples, o token é enviado por uma conexão sem criptografia; use apenas em redes confiáveis ou ative o HTTPS
• O TCP legado não tem autenticação (sem alterações)

HTTPS (TLS)

Quando Usar HTTPS está ativado, o app gera uma Autoridade Certificadora (CA) local privada e um certificado de servidor assinado por essa CA. Os clientes precisam confiar na CA exportada antes de poder se conectar via https://.

Ativando o HTTPS

1. Abra a tela do Servidor pela navegação da barra lateral
2. Ative Usar HTTPS
3. Toque em Exportar certificado CA e use a folha de compartilhamento para enviar via AirDrop ou salvar o arquivo da CA em cada dispositivo cliente
4. Inicie o servidor; confirme que a URL do endpoint muda para https://

Confiando na CA nos clientes

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

1. Exporte a CA na tela do Servidor no iPhone
2. Abra o PEM no Acesso às Chaves no Mac cliente
3. Configure Confiar → Sempre confiar

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

As pontes Node (mcp-remote) só podem usar NODE_OPTIONS=--use-system-ca quando o Node atende a:

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 possa ler. Usar --use-system-ca em uma versão do Node não compatível impede que o processo seja iniciado.

Escopo de confiança: --use-system-ca confia em todo o Chaveiro do sistema, não apenas na CA deste app. NODE_EXTRA_CA_CERTS restringe a confiança a um único arquivo PEM (alternativa em versões mais antigas do Node). O flag está documentado para macOS/Windows.

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

A impressão digital da CA é exibida na tela do Servidor para que você possa verificar se exportou o certificado correto.

Alterações de IP LAN no iOS

Quando o IP de rede local do seu iPhone muda, o app regenera o certificado do servidor com Subject Alternative Names atualizados e reinicia o listener HTTPS. Copie novamente a URL do endpoint se o IP tiver mudado. O certificado da CA permanece o mesmo, a menos que você o regenere desativando e reativando o HTTPS.

Exemplo de endpoint HTTPS

https://192.168.1.42:9000/mcp

Substitua o host pelo valor exibido na tela do Servidor.

Versão do contrato

Versão	Nomes das ferramentas TCP	Notas
v1.1.0 (padrão)	get_*	Recomendada para novas configurações
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 sempre usa os nomes de ferramentas get_*; a versão do contrato afeta apenas os padrões do schema.

Configuração do cliente

A tela do Servidor inclui trechos para copiar e colar de cada integração. Use o endpoint e o token exibidos ali. Verifique os formatos com a versão do seu cliente.

Todos os exemplos abaixo usam um endereço LAN de exemplo; substitua pelo endereço do seu iPhone exibido na tela 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 / arquivo 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 se conecta via Streamable HTTP diretamente, sem precisar de uma ponte Node.js. A configuração fica em ~/.codex/config.toml (global) ou em .codex/config.toml dentro de um diretório de projeto confiável.

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 dentro de uma sessão do Codex para verificar se o servidor está conectado.

Se você regenerar o token Bearer no Health Auto Export, atualize HAE_MCP_TOKEN e execute novamente codex mcp add, ou remova e adicione novamente a entrada do servidor.

mcp-remote (iOS / LAN)

Para clientes somente stdio (como o Claude Desktop) que não conseguem se conectar 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) na tela 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 do iPhone e confie nela no Acesso às Chaves (Sempre confiar) no seu Mac
2. Use https://192.168.1.42:9000/mcp em args
3. Quando o Node atender à 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.

Reduzindo a latência de inicialização: o npx -y baixa o mcp-remote na primeira execução e verifica novamente quando o cache expira, o que pode causar atrasos de vários segundos. Instalar globalmente elimina isso:

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 deslocamento de fuso horário

TCP

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

Dicas

1. Mantenha o Health Auto Export em primeiro plano no iPhone enquanto houver clientes conectados
2. Gere um novo token se suspeitar que ele foi exposto
3. Copie novamente a URL do endpoint depois que o IP LAN do seu iPhone mudar

Suporte por chat

Reúna diagnósticos a partir dos logs de eventos do app em Ajustes → Avançado → Exportar logs de eventos. Veja o Guia de logs de eventos do app. Compartilhe o arquivo zip gerado pelo Suporte por Chat ou por e-mail.