HealthyApps Help Center

서버에 연결

로컬 네트워크의 AI 클라이언트 및 스크립트를 위해 Health Auto Export MCP 서버에 연결하세요.

Last updated: July 14, 2026

이 페이지에서

서버 연결 가이드

iOS의 MCP 서버를 사용하면 로컬 네트워크에 있는 AI 클라이언트와 스크립트가 건강 데이터를 조회할 수 있습니다. HTTP(Streamable MCP)가 권장 전송 방식입니다. iOS는 Node 브리지 구성을 위해 TCP도 지원합니다.

클라이언트는 Mac이나 동일한 네트워크의 다른 기기에서 실행되며, iPhone에 표시된 엔드포인트에 연결합니다.

개요

전송 방식 엔드포인트
HTTP(권장) http://{LAN_IP}:9000/mcp(HTTPS를 사용 중이면 https://)
TCP {LAN_IP}:9000(인증 없음)

{LAN_IP}는 서버가 실행 중일 때 서버 화면에 표시되는 주소로 바꿔서 사용하세요.

사용 사례:

  • Mac의 Claude Code, Codex, Cursor, VS Code를 iPhone의 건강 데이터에 연결
  • Claude Desktop과 같은 stdio 전용 클라이언트에는 mcp-remote(iOS / LAN) 사용
  • 로컬 네트워크의 스크립트에서 지표와 운동 데이터 조회(HTTP)
  • health-auto-export-mcp-server Node 브리지를 통한 TCP 연동

사전 준비 사항

  • iPhone에서 Health Auto Export 실행 중(클라이언트가 연결된 동안 앱을 포그라운드로 유지해야 함)
  • 프리미엄 구독
  • HTTP: 서버 화면의 Bearer 토큰
  • iPhone의 로컬 네트워크 권한
  • 클라이언트 기기: iPhone과 동일한 Wi‑Fi 또는 LAN에 연결. **mcp-remote(iOS / LAN)**를 사용하는 경우에만 Node.js 필요

서버 시작하기

  1. iPhone에서 사이드바 내비게이션을 사용해 서버를 엽니다
  2. HTTP(권장) 또는 TCP를 선택합니다
  3. 필요하면 HTTPS 사용을 활성화합니다(아래 안내 참고)
  4. 서버 시작을 탭합니다
  5. 엔드포인트 URL과 Bearer 토큰을 복사합니다

Health Auto Export가 백그라운드로 전환되면 서버는 자동으로 중지됩니다(HTTP와 TCP 모두).

인증(HTTP)

모든 HTTP 요청에는 다음이 필요합니다:

Authorization: Bearer <your-token>
  • 필요하다고 판단되면 서버 화면에서 토큰을 재생성하세요
  • 일반 HTTP에서는 토큰이 암호화되지 않은 연결로 전송됩니다. 신뢰할 수 있는 네트워크에서만 사용하거나 HTTPS를 활성화하세요
  • TCP 레거시에는 인증이 없습니다(변경 없음)

HTTPS(TLS)

HTTPS 사용이 활성화되면 앱은 프라이빗 로컬 인증 기관(CA)과 해당 CA가 서명한 서버 리프 인증서를 생성합니다. 클라이언트는 https://로 연결하기 전에 내보낸 CA를 신뢰해야 합니다.

HTTPS 활성화하기

  1. 사이드바 내비게이션을 사용해 서버 화면을 엽니다
  2. HTTPS 사용을 켭니다
  3. CA 인증서 내보내기를 탭하고 공유 시트를 사용해 각 클라이언트 기기에 AirDrop으로 전송하거나 저장합니다
  4. 서버를 시작합니다 — 엔드포인트 URL이 https://로 바뀌는지 확인합니다

클라이언트에서 CA 신뢰하기

내보낸 CA를 AI 클라이언트를 실행하는 기기(보통 Mac)에서 신뢰하도록 설정합니다:

  1. iPhone의 서버 화면에서 CA를 내보냅니다
  2. 클라이언트 Mac의 키체인 접근에서 PEM 파일을 엽니다
  3. 신뢰 → 항상 신뢰로 설정합니다

--use-system-ca를 위한 Node 최소 버전

Node 브리지(mcp-remote)는 Node가 다음 조건을 충족할 때만 NODE_OPTIONS=--use-system-ca를 사용할 수 있습니다:

Node 라인 최소 버전
22.x 22.19.0
23.x 23.8.0
24.x 24.6.0
25+ 모든 버전

이보다 낮은 Node 버전에서는 대신 NODE_EXTRA_CA_CERTS를 브리지 프로세스가 읽을 수 있는 PEM 경로로 설정하세요. 지원되지 않는 Node에서 --use-system-ca를 지정하면 프로세스가 시작되지 않습니다.

신뢰 범위: --use-system-ca는 이 앱의 CA뿐 아니라 시스템 키체인 전체를 신뢰합니다. NODE_EXTRA_CA_CERTS는 신뢰 범위를 단일 PEM 파일로 제한합니다(구버전 Node의 대체 방법). 이 플래그는 macOS/Windows에서 문서화되어 있습니다.

클라이언트 유형 설정
Cursor, VS Code, Claude Code, Codex 클라이언트 Mac에서 키체인 신뢰 설정 — 서버 화면의 https:// 엔드포인트 사용
mcp-remote(iOS / LAN) mcp-remote를 실행하는 Mac의 키체인에서 CA를 신뢰합니다. Node가 최소 버전을 충족하면 스니펫이 NODE_OPTIONS=--use-system-ca를 사용합니다. 구버전 Node에서는 NODE_EXTRA_CA_CERTS를 읽을 수 있는 PEM 경로로 설정하세요
curl / 스크립트 --cacert /path/to/mcp-ca.pem을 지정하거나 NODE_EXTRA_CA_CERTS를 설정하세요

CA 지문은 서버 화면에 표시되므로 올바른 인증서를 내보냈는지 확인할 수 있습니다.

iOS의 LAN IP가 변경된 경우

iPhone의 LAN IP가 변경되면 앱은 업데이트된 Subject Alternative Names로 리프 인증서를 다시 생성하고 HTTPS 리스너를 재시작합니다. IP가 변경되었다면 엔드포인트 URL을 다시 복사하세요. HTTPS를 껐다가 다시 켜서 CA를 재생성하지 않는 한 CA 인증서는 동일하게 유지됩니다.

HTTPS 엔드포인트 예시

https://192.168.1.42:9000/mcp

호스트 부분은 서버 화면에 표시된 값으로 바꾸세요.

계약 버전

버전 TCP 도구 이름 참고
v1.1.0(기본값) get_* 신규 설정에 권장
v1.0.0 레거시(health_metrics 등) Claude Desktop 호환성 업데이트 v1.0.0
v0.0.1 레거시 가장 오래된 호환성

HTTP는 항상 get_* 도구 이름을 사용합니다. 계약 버전은 스키마 기본값에만 영향을 줍니다.

클라이언트 설정

서버 화면에는 각 연동을 위한 복사-붙여넣기 스니펫이 포함되어 있습니다. 거기 표시된 엔드포인트와 토큰을 사용하세요. 사용 중인 클라이언트 버전에 맞게 형식을 확인하세요.

아래 예시는 모두 예시용 LAN 주소를 사용합니다. iPhone의 서버 화면에 표시된 주소로 바꾸세요.

Claude Code(CLI)

Mac에서 실행합니다(Claude Code CLI 필요):

HTTP:

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

HTTPS(Mac에서 CA를 내보내고 신뢰한 후):

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

Claude Code / 프로젝트 파일(.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는 Streamable HTTP를 통해 직접 연결하므로 Node.js 브리지가 필요하지 않습니다. 설정은 ~/.codex/config.toml(전역) 또는 신뢰할 수 있는 프로젝트 디렉터리의 .codex/config.toml에 저장됩니다.

CLI(권장):

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 설정:

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

Codex를 시작하기 전에 Bearer 토큰으로 HAE_MCP_TOKEN을 내보내세요. 설정 후 Codex 세션 안에서 /mcp를 실행해 서버가 연결되었는지 확인하세요.

Health Auto Export에서 Bearer 토큰을 재생성했다면 HAE_MCP_TOKEN을 업데이트하고 codex mcp add를 다시 실행하거나, 서버 항목을 제거한 뒤 다시 추가하세요.

mcp-remote(iOS / LAN)

HTTP로 직접 연결할 수 없는 stdio 전용 클라이언트(예: Claude Desktop)를 위한 방법입니다. 클라이언트를 실행하는 Mac에 Node.js가 필요합니다.

  1. iPhone에서 서버를 시작하고 엔드포인트와 토큰을 복사합니다
  2. Mac에서 서버 화면의 **mcp-remote(iOS / LAN)**를 선택해 JSON 스니펫을 복사하거나, 다음 내용을 클라이언트의 MCP 설정에 붙여넣습니다(Claude Desktop → 설정 → 개발자 → 설정 편집):
{
  "command": "npx",
  "args": [
    "-y",
    "mcp-remote@0.1.16",
    "http://192.168.1.42:9000/mcp",
    "--transport",
    "http-only",
    "--header",
    "Authorization: Bearer <token>"
  ]
}

HTTPS가 활성화된 경우:

  1. iPhone에서 CA를 내보내고 Mac의 키체인 접근에서 신뢰합니다(항상 신뢰)
  2. args에서 https://192.168.1.42:9000/mcp를 사용합니다
  3. Node가 --use-system-ca의 최소 버전(22.x는 22.19.0, 23.x는 23.8.0, 24.x는 24.6.0, 25 이상은 모든 버전)을 충족하면 다음을 추가합니다:
"env": {
  "NODE_OPTIONS": "--use-system-ca"
}

구버전 Node에서는 대신 NODE_EXTRA_CA_CERTS를 읽을 수 있는 PEM 경로로 설정하세요. 설정을 업데이트한 후 stdio 클라이언트를 재시작하세요.

시작 지연 줄이기: npx -y는 처음 사용할 때 mcp-remote를 다운로드하고 캐시가 만료될 때마다 다시 확인하므로 몇 초씩 지연될 수 있습니다. 전역으로 미리 설치하면 이를 없앨 수 있습니다:

npm install -g mcp-remote@0.1.16

도구 인자

날짜 형식

start와 end 매개변수는 두 가지 형식을 지원합니다:

형식 예시 참고
yyyy-MM-dd 2026-06-13 시작일: 00:00:00, 종료일: 23:59:59
yyyy-MM-dd HH:mm:ss Z 2026-06-13 00:00:00 +0000 명시적인 시간 및 시간대 오프셋

TCP

  • 포트 9000에서 암호화되지 않고 인증되지 않는 JSON-RPC
  • 레거시 도구 이름에는 Node health-auto-export-mcp-server 브리지와 계약 v1.0.0을 사용하세요
  • get_* TCP 도구 이름에는 계약 v1.1.0을 사용하세요(Node 브리지는 별도로 업데이트 필요)

팁

  1. 클라이언트가 연결된 동안 iPhone에서 Health Auto Export를 포그라운드로 유지하세요
  2. 토큰이 노출되었다고 의심되면 재생성하세요
  3. iPhone의 LAN IP가 변경된 후에는 엔드포인트 URL을 다시 복사하세요

채팅 지원

설정 → 고급 → 이벤트 로그 내보내기로 내보낸 앱 이벤트 로그에서 진단 정보를 수집하세요. 앱 이벤트 로그 가이드를 참고하세요. 생성된 zip 파일을 채팅 지원 또는 이메일로 공유하세요.