Server Connection Guide

The MCP Server on iOS lets AI clients and scripts on your local network query your health data. HTTP (Streamable MCP) is the recommended transport. iOS also supports TCP for Node-bridge setups.

Clients run on your Mac or other devices on the same network and connect to the endpoint shown on your iPhone.

Overview

Transport	Endpoint
HTTP (recommended)	http://{LAN_IP}:9000/mcp (or https:// when HTTPS is enabled)
TCP	{LAN_IP}:9000 (unauthenticated)

Replace {LAN_IP} with the address shown on the Server screen while the server is running.

Use cases:

• Connect Claude Code, Codex, Cursor, or VS Code on your Mac to health data on your iPhone
• Use mcp-remote (iOS / LAN) for stdio-only clients such as Claude Desktop
• Query metrics and workouts from scripts on your local network (HTTP)
• TCP integrations via the health-auto-export-mcp-server Node bridge

Prerequisites

• Health Auto Export on iPhone (app must stay in the foreground while clients are connected)
• Premium subscription
• HTTP: Bearer token from the Server screen
• Local Network permission on iPhone
• Client device: Same Wi‑Fi or LAN as the iPhone; Node.js only if you use mcp-remote (iOS / LAN)

Starting the server

1. On iPhone, open the Server using the sidebar navigation
2. Choose HTTP (recommended) or TCP
3. Optionally enable Use HTTPS (instructions below)
4. Tap Start Server
5. Copy the endpoint URL and bearer token

The server stops automatically if Health Auto Export is backgrounded (both HTTP and TCP).

Authentication (HTTP)

All HTTP requests require:

Authorization: Bearer <your-token>

• Regenerate the token from the Server screen if deemed necessary
• On plain HTTP, the token is sent over an unencrypted connection—use only on trusted networks, or enable HTTPS
• TCP legacy has no authentication (unchanged)

HTTPS (TLS)

When Use HTTPS is enabled, the app generates a private local Certificate Authority (CA) and a server leaf certificate signed by that CA. Clients must trust the exported CA before they can connect over https://.

Enabling HTTPS

1. Open the Server view using the sidebar navigation
2. Turn on Use HTTPS
3. Tap Export CA Certificate and use the share sheet to AirDrop or save the CA file on each client device
4. Start the server — ensure the endpoint URL switches to https://

Trusting the CA on clients

Trust the exported CA on the device running the AI client (usually your Mac):

1. Export the CA from the Server screen on iPhone
2. Open the PEM in Keychain Access on the client Mac
3. Set Trust → Always Trust

Node minimum version for --use-system-ca

Node bridges (mcp-remote) may use NODE_OPTIONS=--use-system-ca only when Node meets:

Node line	Minimum version
22.x	22.19.0
23.x	23.8.0
24.x	24.6.0
25+	any

On older Node, set NODE_EXTRA_CA_CERTS to a PEM path the bridge process can read instead. Emitting --use-system-ca on unsupported Node prevents the process from starting.

Trust scope: --use-system-ca trusts the full system Keychain, not only this app’s CA. NODE_EXTRA_CA_CERTS pins trust to a single PEM file (fallback on older Node). The flag is documented for macOS/Windows.

Client type	Setup
Cursor, VS Code, Claude Code, Codex	Keychain trust on the client Mac — use the https:// endpoint from the Server screen
mcp-remote (iOS / LAN)	Trust CA in Keychain on the Mac running mcp-remote. Snippet uses NODE_OPTIONS=--use-system-ca when Node meets the minimum version; on older Node set NODE_EXTRA_CA_CERTS to a readable PEM path
curl / scripts	Pass --cacert /path/to/mcp-ca.pem or set NODE_EXTRA_CA_CERTS

The CA fingerprint is shown on the Server screen so you can verify you exported the correct certificate.

iOS LAN IP changes

When your iPhone's LAN IP changes, the app regenerates the leaf certificate with updated Subject Alternative Names and restarts the HTTPS listener. Re-copy the endpoint URL if the IP changed. The CA certificate stays the same unless you regenerate it by toggling HTTPS off and on.

Example HTTPS endpoint

https://192.168.1.42:9000/mcp

Replace the host with the value shown on the Server screen.

Contract version

Version	TCP tool names	Notes
v1.1.0 (default)	get_*	Recommended for new setups
v1.0.0	Legacy (health_metrics, …)	Claude Desktop compatibility update v1.0.0
v0.0.1	Legacy	Oldest compatibility

HTTP always uses get_* tool names; contract version affects schema defaults only.

Client configuration

The Server screen includes copy-paste snippets for each integration. Use the endpoint and token shown there. Verify formats against your client version.

All examples below use a placeholder LAN address—substitute your iPhone’s address from the Server screen.

Claude Code (CLI)

Run on your Mac (requires the Claude Code CLI):

HTTP:

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

HTTPS (after exporting and trusting the CA on your Mac):

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

Claude Code / project file (.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 connects over Streamable HTTP directly — no Node.js bridge required. Configuration lives in ~/.codex/config.toml (global) or .codex/config.toml in a trusted project directory.

CLI (recommended):

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

Manual config.toml:

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

Export HAE_MCP_TOKEN with your bearer token before starting Codex. After setup, run /mcp inside a Codex session to verify the server is connected.

If you regenerate the bearer token in Health Auto Export, update HAE_MCP_TOKEN and re-run codex mcp add, or remove and re-add the server entry.

mcp-remote (iOS / LAN)

For stdio-only clients (such as Claude Desktop) that cannot connect over HTTP directly. Requires Node.js on the Mac running the client.

1. Start the server on iPhone and copy the endpoint and token
2. On your Mac, select mcp-remote (iOS / LAN) on the Server screen and copy the JSON snippet, or paste this into the client’s MCP config (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>"
  ]
}

When HTTPS is enabled:

1. Export the CA from iPhone and trust it in Keychain Access (Always Trust) on your Mac
2. Use https://192.168.1.42:9000/mcp in args
3. When Node meets the minimum version for --use-system-ca (22.19.0 on 22.x, 23.8.0 on 23.x, 24.6.0 on 24.x, or any 25+ release), add:

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

On older Node, set NODE_EXTRA_CA_CERTS to a readable PEM path instead. Restart the stdio client after updating the config.

Reducing startup latency: npx -y downloads mcp-remote on first use and re-checks on cache expiry, which can cause multi-second delays. Pre-installing globally eliminates this:

npm install -g mcp-remote@0.1.16

Tool arguments

Date formats

The start and end parameters accept two formats:

Format	Example	Notes
yyyy-MM-dd	2026-06-13	Start date: midnight; end date: 23:59:59
yyyy-MM-dd HH:mm:ss Z	2026-06-13 00:00:00 +0000	Explicit time and timezone offset

TCP

• Unencrypted, unauthenticated JSON-RPC on port 9000
• Use contract v1.0.0 with the Node health-auto-export-mcp-server bridge for legacy tool names
• Use contract v1.1.0 for get_* TCP tool names (update the Node bridge separately)

Tips

1. Keep Health Auto Export in the foreground on iPhone while clients are connected
2. Regenerate the token if you suspect it was exposed
3. Re-copy the endpoint URL after your iPhone’s LAN IP changes

Chat Support

Gather diagnostics from export app event logs by going to Settings → Advanced → Export Event Logs. See the App Event Logs Guide. Share the generated zip file via Chat Support or email.