# About vytalLink

Connecting your health data with AI assistants you already use

## Our Mission

We think your health data should actually help you. Our goal is to let AI assistants read your health info safely, privately, and only when you want them to.

We're making health insights available to everyone by connecting your fitness tracker and health apps with AI assistants like ChatGPT and Claude.

## How It Started

vytalLink started because we were frustrated with having health data stuck in different apps with no easy way to understand what it meant.

We knew AI assistants like ChatGPT and Claude could give great health insights, but they needed a safe way to access our personal data. That's what vytalLink does.

## Our Values

### Privacy First

Your health data stays on your phone. We only share it when you ask questions and want answers.

### User Control

You choose what data to share, when to share it, and which AI assistants get to see it.

### Open Innovation

We use open standards like MCP so vytalLink works with different AI platforms.

## Built by Xmartlabs

vytalLink is built by [Xmartlabs](https://xmartlabs.com), a software company that specializes in mobile apps, AI integration, and health tech.

We've been building digital health solutions for over ten years, so we know how important privacy, security, and ease of use are in health apps.

- [Learn About Xmartlabs](https://xmartlabs.com)

---

# ChatGPT Setup Guide

Connect vytalLink with ChatGPT and start getting answers about your health data

_Most Popular Integration_

## What is vytalLink's Custom GPT?

We built a custom version of ChatGPT that knows how to read health data. It understands your fitness metrics and gives you personalized insights about your wellness in your language.

- AI that understands health and fitness data
- Spots trends and patterns in your workouts
- Gives answers in plain English
- Safe connection to your health data

### Example Conversation

- **You:** Show me my sleep patterns for the last week

- **Assistant:** Based on your data, you've been averaging 7.2 hours of sleep per night this week. I notice you're going to bed consistently around 11 PM, which is great for maintaining a healthy sleep schedule! 📊

## How to Set Up ChatGPT Integration

Follow these steps to connect your health data with ChatGPT

### Step 1: Download and Connect the App

Download the vytalLink app and tap "Get Word + PIN" to get your connection details. You'll use these to connect with ChatGPT. Keep the app open while you chat.

### Step 2: Open vytalLink GPT

Click the button below to access our custom ChatGPT designed specifically for health data analysis. Alternatively, you can go to ChatGPT, navigate to the GPTs section, and search for "vytalLink".

#### Direct Access (Recommended)

Click here to open vytalLink GPT directly

- [Open vytalLink GPT](https://chatgpt.com/g/g-68c2fb58447c8191b5af624f6b33bdd6-vytallink)

#### Manual Search

Go to ChatGPT → GPTs → Search for "vytalLink"

- [Browse GPTs](https://chatgpt.com/gpts)

### Step 3: Connect and Start Asking

Ask any question about your health data. When prompted, provide the Word and PIN shown in your mobile app, then start exploring your health insights!

## Example Questions

Here are some questions you can ask ChatGPT about your health data

- What were my average heart rate and steps yesterday?
- Show me my sleep patterns for the last week
- How many calories did I burn during my last workout?
- Compare my activity levels between this month and last month
- What time did I go to bed on average this week?
- Show me my health trends over the past 30 days

## Ready to Get Started?

Download the vytalLink app and start asking ChatGPT about your health data today!

- [Download the VytalLink app](https://vytallink.xmartlabs.com/app)

- [Try vytalLink GPT](https://chatgpt.com/g/g-68c2fb58447c8191b5af624f6b33bdd6-vytallink)

---

# Claude Desktop Bundle Setup

Install vytalLink in Claude Desktop with one double-click

## Prerequisites

What you need before installing the bundle

### vytalLink Mobile App

Use the mobile app to get your connection Word + PIN for Claude Desktop.

- [App Store](https://apps.apple.com/app/id6752308627)
- [Google Play](https://play.google.com/store/apps/details?id=com.xmartlabs.vytallink)

### Claude Desktop

Download Claude Desktop and sign in with your Anthropic account.

- [Download Claude](https://claude.ai/download)

### vytalLink Bundle

Download the latest `.mcpb` file from GitHub. It's signed and ready to install.

- [Download Bundle](https://firebasestorage.googleapis.com/v0/b/vytallink.firebasestorage.app/o/releases%2FVytalLink%20MCP%20Server.mcpb?alt=media)
- [Release Notes](https://github.com/xmartlabs/vytalLink/releases/latest)

## Setup Instructions

Follow these steps to add vytalLink to Claude Desktop

### Step 1: Update and open Claude Desktop

Launch [Claude Desktop](https://claude.ai/download) (install it if you haven't yet) and check for updates via **Settings → About → Check for updates**. Leave the app running; the bundle install requires Claude to be open.

### Step 2: Download the bundle

Click the download button and save `vytallink-mcp-server.mcpb` somewhere easy to find, like your Downloads folder.

### Step 3: Install inside Claude Desktop

Double-click the bundle (or drag it into **Claude Desktop → Settings → Extensions**). Claude will show the vytalLink MCP extension details—click **Install** to confirm.

> If the bundle doesn't open automatically, right-click the file and choose **Open With → Claude Desktop**.

### Step 4: Restart Claude Desktop

Once the installation finishes, quit and relaunch Claude Desktop so the extension loads correctly.

### Step 5: Authenticate with Word + PIN

Use the vytalLink mobile app to generate a connection Word and PIN. Ask Claude to connect using those credentials to start syncing your health data. Keep the app open while you chat.

#### Example Conversation
- **You:** Connect to vytalLink using Word HEALTH7 and PIN sunset42
- **Claude:** Connection complete! You can now explore your health metrics, workouts, and sleep trends.

> Need the manual npm workflow or support for other MCP clients? Visit the [advanced MCP setup guide](/mcp-setup.html) for step-by-step instructions.

## Troubleshooting

Common issues and quick fixes

### Bundle won't open

Right-click the file and choose **Open With → Claude Desktop**. On macOS you may need to approve the download in System Settings.

### Extension missing after install

Restart Claude Desktop. If it still doesn't appear, reinstall the bundle and check that you're running Claude Desktop version 0.13.0 or newer.

### Authentication issues

Generate a fresh Word + PIN from the mobile app and try again. Credentials expire shortly after being issued.

---

# Build a Health Data Agent in 5 Minutes

Developers integrate the VytalLink MCP once. End users connect through the VytalLink app with Word + PIN, then use your agent to read wearable data.

## Why VytalLink

- **Zero Mobile Dev:** No custom app, no HealthKit entitlements, no platform accounts. Just install VytalLink and connect.
- **All Major Wearables:** Apple Health (iOS) and Health Connect (Android) cover most devices that sync to the phone.
- **Real-Time Streaming:** Live metrics while the VytalLink app is active. No polling, no delay.
- **Privacy by Design:** Health data never leaves the device. No cloud copy, nothing stored server-side.

## Get Started in a Few Simple Steps

See the full connection flow first, then wire the MCP tools below.

### How It Works

1. Developer integrates the VytalLink MCP once
2. User gets Word + PIN in VytalLink
3. User connects the developer's agent with Word + PIN
4. Agent queries health data through VytalLink

### Step 1: Integrate the VytalLink server

Start with the minimal setup below, or browse the [examples repo](https://github.com/xmartlabs/vytalLink/tree/main/examples) for complete TypeScript and Python agents.

#### Recommended: Health Kit Template

A batteries-included Python starter kit with clean architecture, CLI, Jupyter notebooks, and a full observability stack (Grafana, Jaeger, LangSmith). More structure than the raw examples — good for hackathons and prototypes that need a solid base.

- [View on GitHub](https://github.com/xmartlabs/vytallink-health-kit)

#### TypeScript Example

```typescript
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

// 1. Create client and transport
const client = new Client({ name: "my-agent", version: "1.0.0" });
const transport = new StdioClientTransport({
  command: "npx",
  args: ["@xmartlabs/vytallink-mcp-server"],
});

// 2. Connect and discover tools
await client.connect(transport);
const { tools } = await client.listTools();
console.log(`Connected: ${tools.length} tools available`);
```

#### Python Example

```python
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

# 1. Connect to VytalLink MCP server
server_params = StdioServerParameters(
    command="npx",
    args=["@xmartlabs/vytallink-mcp-server"],
)

async with stdio_client(server_params) as (read, write):
    async with ClientSession(read, write) as session:
        await session.initialize()
```

### Step 2: Link the user

Send your users the VytalLink app link. The user first opens VytalLink, gets a **Word + PIN** , then goes into your agent and uses those credentials there while VytalLink stays open as the bridge.

#### Share Link

- [Download App](https://vytallink.xmartlabs.com/app)

- Direct link: `https://vytallink.xmartlabs.com/app`

Your agent calls `direct_login` with the user's Word and PIN:

#### TypeScript Example

```typescript
await client.callTool({
  name: "direct_login",
  arguments: { word: "island", code: "828930" },
});
```

#### Python Example

```python
await session.call_tool(
    "direct_login",
    arguments={"word": "island", "code": "828930"},
)
```

### Step 3: Start querying data

Once the user is linked, your agent can start making MCP queries right away. Here's an example that requests the last 7 days of heart rate data:

#### TypeScript Example

```typescript
const result = await client.callTool({
  name: "get_health_metrics",
  arguments: {
    value_type: "HEART_RATE",
    start_time: "2025-01-01T00:00:00Z",
    end_time: "2025-01-07T23:59:59Z",
    group_by: "DAY",
    statistic: "SUM",
  },
});

console.log(result.content);
```

#### Python Example

```python
result = await session.call_tool(
    "get_health_metrics",
    arguments={
        "value_type": "HEART_RATE",
        "start_time": "2025-01-01T00:00:00Z",
        "end_time": "2025-01-07T23:59:59Z",
        "group_by": "DAY",
        "statistic": "SUM",
    },
)

print(result.content)
```

## Good to Know

Read this before you start integrating

- **Runtime - App Must Stay Open:** The VytalLink app needs to be active in the foreground to stream data. If the user backgrounds or closes the app, the data connection pauses until they return.
- **Performance - Send Data in Batches:** When querying large time ranges, the OS may throttle or kill long-running calls. Break requests into smaller date windows and merge the results in your agent.
- **Beta - API is Experimental:** The backend API works well for prototyping and testing, but it is not yet hardened for production traffic. Use it at your own risk and expect possible breaking changes.
- **Data - Response Format:** Tool responses include two representations: `content[0].text` with a human-readable summary for LLMs, and `structuredContent` with the full JSON payload (healthData array, count, success). Use `structuredContent` when you need to parse values programmatically.
- **Data - Multi-Device Deduplication:** The API may return data from multiple devices (different `source_id` values) for the same time period. To avoid double-counting, pick the `source_id` with the most data points and discard the rest.

## Direct HTTP API

For browser-based or server-side integrations that cannot use MCP stdio

- **Endpoint - POST /mcp/call:** Send `{"name": "tool_name", "arguments": {...}}` to `https://api.vytallink.xmartlabs.com/mcp/call`. Authenticate with `Authorization: Bearer <token>` from the `direct_login` response. The token is in `structuredContent.access_token`.
- **Discovery - GET /mcp/tools:** Fetch the current list of available tools, their input schemas, and output schemas. No authentication required. Use this to discover tool names and parameters dynamically.

## MCP Tools Reference

Three tools your agent can call after connecting

- `direct_login`: Logs in with the user's Word + PIN. No browser, no redirect. One tool call.
- `get_summary`: Returns a snapshot across steps, sleep, heart rate, and more for any date range.
- `get_health_metrics`: Query any metric by time range and aggregation: raw, hourly, or daily.

- [API Reference](https://api.vytallink.xmartlabs.com/docs/mcp)
- [llms-full.txt](/llms-full.txt)

---

# Frequently Asked Questions

Answers about setup, privacy, supported platforms, and more

### What does VytalLink do?

VytalLink connects your fitness tracker and health apps to AI assistants like ChatGPT and Claude. You can ask questions about your sleep, workouts, steps, heart rate, and get clear answers.

### Where do I chat?

You chat in ChatGPT on the web or in Claude Desktop on your computer. VytalLink doesn't have its own chat - it just connects your data to your AI assistant.

### Can I use ChatGPT on mobile?

Yes, from the VytalLink app. After connecting, tap "Start Chatting" and it opens the ChatGPT GPT in a built-in browser. That keeps VytalLink running in the foreground so your data keeps flowing. Opening the standalone ChatGPT app instead will break the connection.

### Do I need to keep the app open?

Yes. Keep the VytalLink app open while you chat so it can share your data with your AI assistant. Close the app and your AI can't get new data.

### How do I connect? What are “Word + PIN”?

- Tap “Get Word + PIN” in the app to generate temporary credentials for your current session.
- When ChatGPT or your MCP client asks, paste the Word and PIN to authenticate the bridge.
- These credentials expire; generate new ones anytime.

### Does VytalLink store my health data?

Your phone remains the source of truth. VytalLink is designed to relay only the health data needed for an active session, and not to keep a separate cloud copy of your metrics after that session ends.

### Who receives my data during a session?

You choose who to share your data with during each session. Once shared, the data is subject to the recipient’s policies:

- ChatGPT sessions are subject to OpenAI’s policies and the settings or plan that apply to your account.
- Claude Desktop sessions are subject to Anthropic’s policies.
- For MCP clients (Cursor, VS Code, etc.), data flows to the provider behind that client.

Review the provider’s terms before sharing. VytalLink does not sell or repurpose your health data.

### Which devices and platforms are supported?

- **iOS:** Apple Health (Apple Watch and many third‑party wearables that sync to Health).
- **Android:** Health Connect (support varies by device/app; we’re expanding coverage).

If your wearable syncs to your phone’s health platform, VytalLink can make that data conversational.

### Do I need MCP to get started?

No. The fastest path is ChatGPT (no desktop setup). MCP is available for desktop workflows and power users.

### What kind of questions can I ask?

- “Analyze my sleep last month vs. the previous one. Any recommendations?”
- “How did deep sleep change on strength days vs. cardio?”
- “Chart my heart rate over the last month and highlight trends.”
- “Are my steps up this month, and how did resting HR respond?”

### Why might results vary?

AI answers depend on the model and your prompts. Try concrete time ranges, comparisons, or goals. We recommend verifying any critical insights and consulting professionals for medical decisions.

### How do I revoke access or disconnect?

Stop the connection in the mobile app or simply close the app to pause the bridge. Since credentials expire and the relay is stateless, access ends when the session does. You can generate new credentials at any time.

### Do I need to register to use the app?

No account is required to start using VytalLink. The app is designed to work without a sign-up flow, so you can connect your health data without creating a separate VytalLink account.

### What is MCP?

MCP stands for Model Context Protocol. It’s a standard that allows desktop clients like Claude Desktop, Cursor, or VS Code to interact with your health data securely and efficiently. MCP clients provide advanced workflows for power users.

### Which client should I use?

- **ChatGPT:** Best for quick, conversational insights. No desktop setup required.
- **Claude Desktop:** Ideal for users who prefer Anthropic’s AI and desktop workflows.
- **Other MCP clients:** Use these for specific integrations or advanced setups.

Choose the client that aligns with your workflow and preferences.

### Troubleshooting

- **Authentication failed:** generate a fresh Word + PIN and try again.
- **No data visible:** ensure the app has health permissions and stays open.
- **MCP server not found:** confirm the MCP server/package is installed or the Claude bundle is enabled; restart the client.
- **Connection lost:** check network connectivity and restart the session.

### Disclaimers

VytalLink does not provide medical advice, diagnosis, or treatment. For medical questions, consult a qualified professional.

### What is the difference between ChatGPT and MCP clients?

ChatGPT is ideal for quick, conversational insights without any desktop setup. MCP clients, like Claude Desktop or VS Code, are designed for advanced workflows and professional use cases.

### What happens if I close the app during a session?

If you close the app, the connection to your AI assistant is paused, and no new data will be relayed. To resume, simply reopen the app and restart the session.

### Can I use VytalLink offline?

No, VytalLink requires an active internet connection to securely relay your health data to your AI assistant.

### What data does VytalLink access from my phone?

VytalLink accesses only the health metrics you approve, such as sleep, workouts, steps, and heart rate. You have full control over what data is shared during each session.

### How is my privacy protected?

VytalLink is designed to keep your health data on your phone until you choose to share it with a connected assistant. Only the information needed for the current session is relayed, and you can stop sharing by ending the session or closing the app.

### Why don’t I see all my data, like sleep details?

1. Your wearable might not sync all data to Apple Health (iOS) or Health Connect (Android). Ensure your device is properly connected and syncing.
2. Some wearables only share limited data. For example, they might log a sleep session but not provide detailed sleep stages (like deep or REM sleep).

### Can I use VytalLink with multiple AI clients simultaneously?

Yes, you can connect to multiple AI clients simultaneously. However, we recommend maintaining a single active connection for simplicity and to avoid potential data conflicts.

### What MCP tools does VytalLink expose?

- `direct_login` — authenticates the user with their Word + PIN. No browser, no redirect.
- `get_summary` — returns a snapshot of steps, sleep, heart rate, and more for any date range.
- `get_health_metrics` — queries a specific metric by time range and aggregation (raw, hourly, or daily).

Full parameter reference, schemas, and response types in the [API Reference](https://api.vytallink.xmartlabs.com/docs/mcp).

### How does the user connect to my agent?

The user opens the VytalLink app and taps to get a Word + PIN, then enters those credentials inside your agent. Your agent calls `direct_login` with the Word and PIN to establish the session. The user must keep the VytalLink app open for the connection to stay active.

### What languages and SDKs are supported?

Any language with an MCP client SDK works. The [examples repo](https://github.com/xmartlabs/vytalLink/tree/main/examples) includes TypeScript and Python agents. You can also start from the [Health Kit Template](https://github.com/xmartlabs/vytallink-health-kit), a Python starter with CLI, Jupyter notebooks, and an observability stack.

### Why does my agent stop getting data when the user switches apps?

The VytalLink app must be active in the foreground to stream data. If the user backgrounds or closes the app, the data connection pauses until they return and reopen it. There is no background data mode.

### How should I handle large time ranges?

The OS may throttle or kill long-running calls on large date windows. Break requests into smaller windows (a week at a time works well) and merge the results in your agent.

### Is the API production-ready?

Not yet. The backend works well for prototyping and testing, but it is not hardened for production traffic. Use it at your own risk and expect possible breaking changes.

---

# MCP Setup Guide

Connect vytalLink to any MCP client in a few minutes

Supported clients: Claude Desktop, Cursor, VS Code, and other MCP-compatible clients.

## Prerequisites

What you need before setting up MCP

### vytalLink Mobile App

Download and set up the vytalLink mobile app to generate your connection Word + PIN.

- [App Store](https://apps.apple.com/app/id6752308627)
- [Google Play](https://play.google.com/store/apps/details?id=com.xmartlabs.vytallink)

### Node.js & npm

Required to install and run the vytalLink MCP server package.

- [Download Node.js](https://nodejs.org/)

### MCP Client

Any MCP-compatible client like Claude Desktop, Cursor, or VS Code with MCP support.

- [Claude Desktop](https://claude.ai/download)

## Setup Instructions

Choose your MCP client and follow the setup guide

## Claude Desktop

### Step 1: Install the MCP Server

> Looking for the one-click experience? Use the [Claude Desktop bundle guide](/claude-bundle-setup.html) instead.

Install the vytalLink MCP server package globally using npm:

#### Terminal

```
npm install -g @xmartlabs/vytallink-mcp-server
```

### Step 2: Configure Claude Desktop

Add vytalLink to your Claude Desktop configuration file:

#### Configuration File Locations

- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux:** `~/.config/claude/claude_desktop_config.json`

#### claude_desktop_config.json

```json
{
  "mcpServers": {
    "vytalLink": {
      "command": "npx",
      "args": [
        "@xmartlabs/vytallink-mcp-server"
      ]
    }
  }
}
```

### Step 3: Restart Claude Desktop

Close and restart Claude Desktop to load the new MCP server configuration.

### Step 4: Connect Your Health Data

Use the Word + PIN from your vytalLink mobile app to authenticate:

#### Example Conversation
- **You:** Connect to my health data using Word HEALTH7 and PIN sunset42
- **Claude:** I've successfully connected to your health data! I can now help you analyze your fitness metrics, sleep patterns, and wellness trends.

## Cursor

### Step 1: Install the MCP Server

Install the vytalLink MCP server package:

#### Terminal

```
npm install -g @xmartlabs/vytallink-mcp-server
```

### Step 2: Configure Cursor

Add vytalLink to your Cursor MCP configuration:

#### Cursor MCP Configuration

```json
{
  "mcpServers": {
    "vytalLink": {
      "command": "npx",
      "args": [
        "@xmartlabs/vytallink-mcp-server"
      ]
    }
  }
}
```

### Step 3: Enable MCP in Cursor

Make sure MCP is enabled in Cursor settings and restart the application.

> Check Cursor's documentation for the latest MCP setup instructions

## VS Code

### Step 1: Install MCP Extension

Install an MCP-compatible extension in VS Code (availability may vary).

> MCP support in VS Code is evolving. Check the VS Code marketplace for MCP extensions.

### Step 2: Install the MCP Server

#### Terminal

```
npm install -g @xmartlabs/vytallink-mcp-server
```

### Step 3: Configure MCP Server

Create or edit the MCP configuration file in your VS Code user directory:

#### Configuration File Locations

- **macOS:** `~/Library/Application Support/Code/User/mcp.json`
- **Windows:** `%APPDATA%\Code\User\mcp.json`
- **Linux:** `~/.config/Code/User/mcp.json`

#### mcp.json

```json
{
  "servers": {
    "vytalLink": {
      "command": "npx",
      "args": ["@xmartlabs/vytallink-mcp-server"]
    }
  }
}
```

### Step 4: Restart VS Code

Close and restart VS Code to load the new MCP server configuration.

## Other MCP Clients

### Step 1: Install the MCP Server

#### Terminal

```
npm install -g @xmartlabs/vytallink-mcp-server
```

### Step 2: Generic MCP Configuration

Use this configuration template for any MCP-compatible client:

#### MCP Configuration Template

```json
{
  "mcpServers": {
    "vytalLink": {
      "command": "npx",
      "args": [
        "@xmartlabs/vytallink-mcp-server"
      ]
    }
  }
}
```

### Step 3: Client-Specific Setup

Follow your MCP client's documentation to:

- Add the server configuration
- Enable MCP functionality
- Restart the application

## Troubleshooting

Common issues and solutions

### MCP server not found

Verify that @xmartlabs/vytallink-mcp-server is installed globally and npx is available in your PATH.

### Authentication failed

Check that you're using the correct Word + PIN from your vytalLink mobile app. Credentials expire after some time.

### No health data

Ensure your mobile app has permission to access health data and is actively syncing with your device's health platform.

## Need More Help?

If you're still having issues, check our documentation or reach out for support:

- [GitHub Repository](https://github.com/xmartlabs/vytalLink)
- [Contact Support](https://xmartlabs.com)

---

# MCP API Reference

## Authentication — direct_login

Call `direct_login` via `POST /mcp/call` to get a Bearer token. No Authorization header needed for this call.

**Request — exact field names (common mistakes in bold):**
- `word` (string, required) — the connection keyword from the VytalLink app (e.g. `"island"`). **Not** `connection_word`, `username`, or `user_word`.
- `code` (string, required) — the 6-digit PIN from the VytalLink app (e.g. `"828930"`). **Not** `pin`, `password`, or `otp`.

```json
{
  "name": "direct_login",
  "arguments": { "word": "island", "code": "828930" }
}
```

**Response — token location:**
```json
{
  "content": [{ "type": "text", "text": "Authentication successful! ..." }],
  "structuredContent": {
    "success": true,
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "Bearer",
    "expires_in": 7200
  }
}
```
Read the token from `structuredContent.access_token`. **It is not in `content[0].text`** (the text field contains it as prose, but parse `structuredContent` — never regex the text field).

Use the token in all subsequent calls: `Authorization: Bearer <access_token>`.

**On failure** (wrong word/code), the HTTP status is still 200 but `structuredContent.success` is `false` and an `error` key is present at the top level. Always check `structuredContent.success` before reading the token.

## Response format

Every tool response has two fields:
- `content[0].text`: human-readable summary for LLMs
- `structuredContent`: full JSON payload — **always read from here when parsing programmatically**

The shape of `structuredContent` depends on the tool:
- `get_health_metrics` / `get_summary`: `{ healthData, count, success }`
- `direct_login`: `{ success, access_token, token_type, expires_in, user_id, message }`

**healthData record fields** (for `get_health_metrics` and `get_summary`):
- `type` (string): metric type in the response — **may differ from the `value_type` you sent**. Example: request `value_type: "SLEEP"` returns records with `type: "SLEEP_SESSION"`. Never use response `type` values as `value_type` inputs.
- `value` (number or object): the metric value — number for most metrics, object for WORKOUT
- `unit` (string): unit of measurement, e.g. `count`, `minute`, `meter`
- `date_from` (ISO 8601): start of the measurement period — **field is `date_from`, not `startDate` or `start_time`**
- `date_to` (ISO 8601): end of the measurement period
- `source_id` (string): identifies the app or device that recorded the data (e.g. `com.apple.health`, `com.google.android.apps.fitness`)

## value_type → response type mapping

The `type` field in `healthData[]` is **not always the same** as the `value_type` you sent. Some categories return multiple records with different type names. Never use response `type` values as `value_type` inputs — always use the left column.

| value_type (request) | type values in response healthData[] |
|----------------------|--------------------------------------|
| STEPS | STEPS |
| HEART_RATE | HEART_RATE, RESTING_HEART_RATE |
| CALORIES | TOTAL_CALORIES_BURNED, ACTIVE_ENERGY_BURNED |
| BLOOD_OXYGEN | BLOOD_OXYGEN |
| BLOOD_PRESSURE | BLOOD_PRESSURE_SYSTOLIC, BLOOD_PRESSURE_DIASTOLIC |
| BODY_TEMPERATURE | BODY_TEMPERATURE |
| BODY_METRICS | WEIGHT, HEIGHT, BODY_FAT_PERCENTAGE, WATER, NUTRITION |
| GLUCOSE | BLOOD_GLUCOSE |
| EXERCISE_TIME | EXERCISE_TIME |
| RESPIRATORY_RATE | RESPIRATORY_RATE |
| WALKING_SPEED | WALKING_SPEED |
| SLEEP | SLEEP_SESSION (aggregated); SLEEP_ASLEEP, SLEEP_REM, SLEEP_DEEP, SLEEP_LIGHT, SLEEP_IN_BED, SLEEP_AWAKE, etc. (raw) |
| MINDFULNESS | MINDFULNESS |
| WORKOUT | WORKOUT |
| DISTANCE | DISTANCE_WALKING_RUNNING, DISTANCE_DELTA |

## get_health_metrics parameters

Required: `value_type`, `start_time`, `end_time`. Optional: `group_by`, `statistic`.

**Parameter names are exact — do not use aliases** (`metric_type`, `start_date`, `end_date`, `aggregation` are not valid).

```json
{
  "name": "get_health_metrics",
  "arguments": {
    "value_type": "STEPS",
    "start_time": "2026-01-01T00:00:00Z",
    "end_time": "2026-01-31T23:59:59Z",
    "group_by": "DAY",
    "statistic": "SUM"
  }
}
```

## Units per metric

| value_type | Unit | value field type | Notes |
|-----------|------|-----------------|-------|
| STEPS | count | number | number of steps |
| HEART_RATE | beats_per_minute | number | response returns two records: HEART_RATE and RESTING_HEART_RATE |
| CALORIES | kcal | number | response returns two records: TOTAL_CALORIES_BURNED and ACTIVE_ENERGY_BURNED — sum them for total kcal |
| BLOOD_OXYGEN | percent | number | blood oxygen saturation |
| BLOOD_PRESSURE | mmHg | number | response returns two records: BLOOD_PRESSURE_SYSTOLIC and BLOOD_PRESSURE_DIASTOLIC |
| BODY_TEMPERATURE | celsius | number | body temperature |
| BODY_METRICS | units vary | number | weight, height, body fat, water, nutrition |
| GLUCOSE | mg/dL | number | response type is BLOOD_GLUCOSE (not GLUCOSE) |
| EXERCISE_TIME | minute | number | minutes of exercise. May return empty (count: 0) depending on the user's device. Check count before using |
| RESPIRATORY_RATE | breaths_per_minute | number | breaths per minute |
| WALKING_SPEED | m/s | number | walking speed |
| SLEEP | minute | number | With group_by: returns SLEEP_SESSION records only — value = total minutes. Without group_by (raw): returns all sleep subtypes per night (SLEEP_SESSION, SLEEP_DEEP, SLEEP_REM, SLEEP_LIGHT, SLEEP_AWAKE, etc.). Use SLEEP_SESSION for total; do NOT sum all types — they overlap. Divide minutes by 60 for hours |
| MINDFULNESS | minute | number | minutes of meditation |
| WORKOUT | noUnit | **object** | object with fields: session_count (int), total_energy_burned (kcal), total_distance (meters), total_steps (int), workout_type (string). NOT a number — requires special parsing |
| DISTANCE | meter | number | response type is DISTANCE_WALKING_RUNNING or DISTANCE_DELTA (not DISTANCE). Value in meters; divide by 1000 for km |

## Response examples

**get_health_metrics response — STEPS (numeric):**

```json
{
  "content": [
    {
      "type": "text",
      "text": "Health metrics retrieved successfully."
    }
  ],
  "structuredContent": {
    "healthData": [
      {
        "type": "STEPS",
        "value": 452387,
        "unit": "count",
        "date_from": "2026-01-01T00:00:00.000Z",
        "date_to": "2026-02-01T00:00:00.000Z",
        "source_id": "com.apple.health"
      }
    ],
    "count": 1,
    "success": true
  }
}
```

**get_health_metrics response — SLEEP (average minutes per night):**

```json
{
  "content": [
    {
      "type": "text",
      "text": "Health metrics retrieved successfully."
    }
  ],
  "structuredContent": {
    "healthData": [
      {
        "type": "SLEEP_SESSION",
        "value": 396.4,
        "unit": "minute",
        "date_from": "2026-01-01T00:00:00.000Z",
        "date_to": "2026-01-31T23:59:59.000Z",
        "source_id": "com.apple.health"
      }
    ],
    "count": 1,
    "success": true
  }
}
```

**get_health_metrics response — WORKOUT (object value):**

```json
{
  "content": [
    {
      "type": "text",
      "text": "Health metrics retrieved successfully."
    }
  ],
  "structuredContent": {
    "healthData": [
      {
        "type": "WORKOUT",
        "value": {
          "workout_type": "OTHER, WALKING, RUNNING",
          "session_count": 54,
          "total_distance": 117666,
          "total_energy_burned": 31274,
          "total_steps": 293746
        },
        "unit": "noUnit",
        "date_from": "2026-01-01T00:00:00.000Z",
        "date_to": "2026-02-01T00:00:00.000Z",
        "source_id": "com.heytap.health.international"
      }
    ],
    "count": 1,
    "success": true
  }
}
```

**get_health_metrics response — empty (metric not available):**

```json
{
  "content": [
    {
      "type": "text",
      "text": "No EXERCISE_TIME metrics found for the specified time range."
    }
  ],
  "structuredContent": {
    "healthData": [],
    "count": 0,
    "success": true
  }
}
```

## Device availability notes

Not all devices report all metrics. EXERCISE_TIME and MINDFULNESS are commonly unavailable. When count is 0 and healthData is empty, the metric is not tracked by the user's device. Handle this gracefully in your integration.

**Multiple sources per time period:** A single call can return multiple entries in `healthData` for the same time period — one per `source_id` (e.g. Google Fit, heytap health, Apple Health). Do not sum across sources. Pick the `source_id` with the most entries and use only those values. Summing all entries will produce inflated totals.