HealthyApps Help Center

Kết nối máy chủ

Kết nối với máy chủ MCP của Health Auto Export cho các AI client và script trong mạng cục bộ của bạn.

Last updated: July 14, 2026

Trên trang này

Hướng dẫn kết nối máy chủ

Máy chủ MCP trên iOS cho phép các AI client và script trong mạng cục bộ của bạn truy vấn dữ liệu sức khỏe. HTTP (Streamable MCP) là phương thức truyền tải được khuyến nghị. iOS cũng hỗ trợ TCP cho các thiết lập dùng Node-bridge.

Các client chạy trên Mac hoặc các thiết bị khác trong cùng mạng và kết nối tới endpoint hiển thị trên iPhone của bạn.

Tổng quan

Phương thức truyền tải Endpoint
HTTP (khuyến nghị) http://{LAN_IP}:9000/mcp (hoặc https:// khi bật HTTPS)
TCP {LAN_IP}:9000 (không xác thực)

Thay {LAN_IP} bằng địa chỉ hiển thị trên màn hình Server trong khi máy chủ đang chạy.

Các trường hợp sử dụng:

  • Kết nối Claude Code, Codex, Cursor hoặc VS Code trên Mac của bạn với dữ liệu sức khỏe trên iPhone
  • Sử dụng mcp-remote (iOS / LAN) cho các client chỉ hỗ trợ stdio như Claude Desktop
  • Truy vấn các chỉ số và bài tập từ script trong mạng cục bộ của bạn (HTTP)
  • Tích hợp qua TCP thông qua Node bridge health-auto-export-mcp-server

Yêu cầu

  • Health Auto Export trên iPhone (ứng dụng phải luôn ở chế độ nền trước khi có client đang kết nối)
  • Gói đăng ký Premium
  • HTTP: Bearer token từ màn hình Server
  • Quyền Mạng cục bộ trên iPhone
  • Thiết bị client: Cùng Wi-Fi hoặc mạng cục bộ với iPhone; chỉ cần Node.js nếu bạn dùng mcp-remote (iOS / LAN)

Khởi động máy chủ

  1. Trên iPhone, mở Server bằng thanh điều hướng bên
  2. Chọn HTTP (khuyến nghị) hoặc TCP
  3. Tùy chọn bật Use HTTPS (hướng dẫn ở dưới)
  4. Nhấn Start Server
  5. Sao chép URL endpoint và bearer token

Máy chủ sẽ tự động dừng nếu Health Auto Export bị chuyển sang chạy nền (cả HTTP và TCP).

Xác thực (HTTP)

Mọi yêu cầu HTTP đều cần:

Authorization: Bearer <your-token>
  • Tạo lại token từ màn hình Server nếu bạn thấy cần thiết
  • Với HTTP thông thường, token được gửi qua kết nối không mã hóa — chỉ sử dụng trên các mạng đáng tin cậy, hoặc bật HTTPS
  • TCP kiểu cũ không có xác thực (không thay đổi)

HTTPS (TLS)

Khi bật Use HTTPS, ứng dụng sẽ tạo một Certificate Authority (CA) cục bộ riêng tư và một chứng chỉ máy chủ được CA đó ký. Client phải tin cậy CA đã xuất trước khi có thể kết nối qua https://.

Bật HTTPS

  1. Mở màn hình Server bằng thanh điều hướng bên
  2. Bật Use HTTPS
  3. Nhấn Export CA Certificate và dùng menu chia sẻ để gửi qua AirDrop hoặc lưu tệp CA trên từng thiết bị client
  4. Khởi động máy chủ — đảm bảo URL endpoint chuyển sang https://

Tin cậy CA trên các client

Thiết lập tin cậy cho CA đã xuất trên thiết bị đang chạy AI client (thường là Mac của bạn):

  1. Xuất CA từ màn hình Server trên iPhone
  2. Mở tệp PEM trong Keychain Access trên Mac của client
  3. Đặt Trust → Always Trust

Phiên bản Node tối thiểu cho --use-system-ca

Các Node bridge (mcp-remote) chỉ có thể dùng NODE_OPTIONS=--use-system-ca khi Node đáp ứng:

Dòng Node Phiên bản tối thiểu
22.x 22.19.0
23.x 23.8.0
24.x 24.6.0
25+ bất kỳ

Với Node cũ hơn, hãy đặt NODE_EXTRA_CA_CERTS thành đường dẫn PEM mà tiến trình bridge có thể đọc được. Việc dùng --use-system-ca trên phiên bản Node không được hỗ trợ sẽ khiến tiến trình không thể khởi động.

Phạm vi tin cậy: --use-system-ca tin cậy toàn bộ Keychain hệ thống, không chỉ CA của riêng ứng dụng này. NODE_EXTRA_CA_CERTS giới hạn sự tin cậy vào một tệp PEM duy nhất (phương án dự phòng cho Node cũ hơn). Cờ này được ghi trong tài liệu dành cho macOS/Windows.

Loại client Thiết lập
Cursor, VS Code, Claude Code, Codex Tin cậy qua Keychain trên Mac của client — dùng endpoint https:// từ màn hình Server
mcp-remote (iOS / LAN) Tin cậy CA trong Keychain trên Mac đang chạy mcp-remote. Đoạn mã sử dụng NODE_OPTIONS=--use-system-ca khi Node đáp ứng phiên bản tối thiểu; với Node cũ hơn, đặt NODE_EXTRA_CA_CERTS thành đường dẫn PEM có thể đọc được
curl / script Truyền --cacert /path/to/mcp-ca.pem hoặc đặt NODE_EXTRA_CA_CERTS

Dấu vân tay (fingerprint) của CA được hiển thị trên màn hình Server để bạn có thể xác minh đã xuất đúng chứng chỉ.

Thay đổi LAN IP trên iOS

Khi LAN IP của iPhone thay đổi, ứng dụng sẽ tạo lại chứng chỉ máy chủ với Subject Alternative Names cập nhật và khởi động lại HTTPS listener. Sao chép lại URL endpoint nếu IP đã thay đổi. Chứng chỉ CA vẫn giữ nguyên trừ khi bạn tạo lại bằng cách tắt rồi bật lại HTTPS.

Ví dụ về endpoint HTTPS

https://192.168.1.42:9000/mcp

Thay host bằng giá trị hiển thị trên màn hình Server.

Phiên bản hợp đồng (contract)

Phiên bản Tên công cụ TCP Ghi chú
v1.1.0 (mặc định) get_* Khuyến nghị cho các thiết lập mới
v1.0.0 Cũ (health_metrics, …) Cập nhật tương thích Claude Desktop v1.0.0
v0.0.1 Cũ Khả năng tương thích cổ nhất

HTTP luôn dùng tên công cụ get_*; phiên bản hợp đồng chỉ ảnh hưởng đến giá trị mặc định của schema.

Cấu hình client

Màn hình Server có các đoạn mã copy-paste cho từng loại tích hợp. Hãy dùng endpoint và token hiển thị ở đó. Kiểm tra định dạng theo phiên bản client của bạn.

Tất cả ví dụ dưới đây dùng địa chỉ LAN mẫu — hãy thay bằng địa chỉ iPhone của bạn từ màn hình Server.

Claude Code (CLI)

Chạy trên Mac của bạn (cần Claude Code CLI):

HTTP:

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

HTTPS (sau khi xuất và tin cậy CA trên Mac của bạn):

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

Claude Code / tệp dự án (.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 kết nối trực tiếp qua Streamable HTTP — không cần Node.js bridge. Cấu hình nằm trong ~/.codex/config.toml (toàn cục) hoặc .codex/config.toml trong một thư mục dự án đáng tin cậy.

CLI (khuyến nghị):

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 thủ công:

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

Xuất biến HAE_MCP_TOKEN với bearer token của bạn trước khi khởi động Codex. Sau khi thiết lập, chạy /mcp trong một phiên Codex để xác minh máy chủ đã kết nối.

Nếu bạn tạo lại bearer token trong Health Auto Export, hãy cập nhật HAE_MCP_TOKEN và chạy lại codex mcp add, hoặc xóa và thêm lại mục máy chủ.

mcp-remote (iOS / LAN)

Dành cho các client chỉ hỗ trợ stdio (như Claude Desktop) không thể kết nối trực tiếp qua HTTP. Yêu cầu Node.js trên Mac đang chạy client.

  1. Khởi động máy chủ trên iPhone và sao chép endpoint cùng token
  2. Trên Mac của bạn, chọn mcp-remote (iOS / LAN) trên màn hình Server và sao chép đoạn mã JSON, hoặc dán vào cấu hình MCP của 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>"
  ]
}

Khi bật HTTPS:

  1. Xuất CA từ iPhone và tin cậy nó trong Keychain Access (Always Trust) trên Mac của bạn
  2. Dùng https://192.168.1.42:9000/mcp trong args
  3. Khi Node đáp ứng phiên bản tối thiểu cho --use-system-ca (22.19.0 với 22.x, 23.8.0 với 23.x, 24.6.0 với 24.x, hoặc bất kỳ bản 25+), thêm:
"env": {
  "NODE_OPTIONS": "--use-system-ca"
}

Với Node cũ hơn, hãy đặt NODE_EXTRA_CA_CERTS thành đường dẫn PEM có thể đọc được thay thế. Khởi động lại client stdio sau khi cập nhật cấu hình.

Giảm độ trễ khởi động: npx -y tải mcp-remote khi dùng lần đầu và kiểm tra lại khi cache hết hạn, điều này có thể gây độ trễ vài giây. Cài đặt sẵn toàn cục sẽ loại bỏ vấn đề này:

npm install -g mcp-remote@0.1.16

Đối số công cụ

Định dạng ngày

Các tham số start và end chấp nhận hai định dạng:

Định dạng Ví dụ Ghi chú
yyyy-MM-dd 2026-06-13 Ngày bắt đầu: nửa đêm; ngày kết thúc: 23:59:59
yyyy-MM-dd HH:mm:ss Z 2026-06-13 00:00:00 +0000 Thời gian và múi giờ rõ ràng

TCP

  • JSON-RPC không mã hóa, không xác thực trên cổng 9000
  • Dùng hợp đồng v1.0.0 với Node bridge health-auto-export-mcp-server cho tên công cụ kiểu cũ
  • Dùng hợp đồng v1.1.0 cho tên công cụ TCP get_* (cập nhật Node bridge riêng)

Mẹo

  1. Giữ Health Auto Export ở chế độ nền trước trên iPhone khi có client đang kết nối
  2. Tạo lại token nếu bạn nghi ngờ nó đã bị lộ
  3. Sao chép lại URL endpoint sau khi LAN IP của iPhone thay đổi

Hỗ trợ qua trò chuyện

Thu thập thông tin chẩn đoán từ nhật ký sự kiện của ứng dụng xuất dữ liệu bằng cách vào Settings → Advanced → Export Event Logs. Xem Hướng dẫn nhật ký sự kiện ứng dụng. Chia sẻ tệp zip đã tạo qua Hỗ trợ trò chuyện hoặc email.