How to Build an AI Agent That Reasons Over Health Data

Open Wearables Team · July 22, 2026 · 5 min read

Key Takeaways

An AI agent that reasons over health data is different from one that reads it. Reading returns numbers. Reasoning connects patterns across metrics, time periods, and user context to produce actionable output.
Open Wearables ships an MCP server that gives any compatible LLM structured, queryable access to health data through five tools: get_users, get_workout_events, get_sleep_summary, get_activity_summary, and get_timeseries.
The MCP server includes a built-in workflow: discover users, determine date range, call the right tool, present results with context. The LLM follows this workflow automatically when configured correctly.
The MCP server is designed for AI assistant interfaces (Claude Desktop, Cursor IDE). For production backend integrations, call the Open Wearables REST API directly.
The reasoning layer is yours to define: which metrics matter, what thresholds apply, what the model should and should not conclude. Open Wearables provides the data access. You provide the domain logic.

Most health AI integrations produce the same output regardless of how sophisticated the model is: a list of numbers with labels. "Your heart rate averaged 72 bpm. You slept 6.4 hours. You walked 8,432 steps." The model is reading, not reasoning.

An agent that reasons over health data does something different. It retrieves specific data for a specific question, interprets it in context, connects it to related metrics, and produces output that a user can act on. This article covers how to build that reasoning layer using Open Wearables.

What the Open Wearables MCP Server Provides

The Open Wearables MCP server is a FastMCP application that exposes five tools and one prompt to any connected AI assistant. It runs as a REST API client on top of your Open Wearables instance.

Five tools:

get_users: Discover users accessible via your API key. Takes an optional search term and limit.
get_workout_events: Retrieve workout sessions for a user within a date range. Filterable by workout type (running, cycling, swimming, strength_training, etc.).
get_sleep_summary: Retrieve daily sleep summaries including duration, stages, and efficiency.
get_activity_summary: Retrieve daily activity metrics: steps, calories, heart rate, distance, intensity minutes.
get_timeseries: Retrieve granular time-series samples for metrics not covered by summary tools (weight, SpO2, HRV, respiratory rate, blood glucose). Capped at 100 pages per call to keep responses bounded.

One prompt:

present_health_data: Formatting guidelines for presenting health data in a human-readable way. Instructs the model to lead with insights, convert units, round appropriately, and highlight patterns rather than dumping raw values.

How the Agent Workflow Works

The MCP server includes a built-in workflow in its system instructions. When a user asks a health question, the agent follows this sequence:

If the user ID is not known, call get_users first
Select the appropriate user based on the query context
Determine the date range: explicit if specified, otherwise default to the last 14 days
Call the appropriate tool with the user ID and date range
Present the result with context and highlights

From the MCP server's system instructions, a sleep query looks like this in practice:

            User: "How did I sleep last week?"

Agent:
1. Calls get_users() to find the user's ID
2. Calculates dates: start_date = 7 days ago, end_date = today
3. Calls get_sleep_summary(user_id="uuid-1", start_date="2026-01-28", end_date="2026-02-04")
4. Responds: "Over the past week, you averaged 7.2 hours of sleep per night.
   Your best night was Tuesday (8.1 hours), and your shortest was Friday (5.9 hours).
   Your sleep efficiency averaged 89%."

Setting Up the MCP Server

            cd mcp
uv sync --group code-quality
cp config/.env.example config/.env
# Set OPEN_WEARABLES_API_URL and OPEN_WEARABLES_API_KEY
uv run start

To connect to Claude Desktop, add to ~/Library/Application Support/Claude/claude_desktop_config.json:

            {
  "mcpServers": {
    "open-wearables": {
      "command": "uv",
      "args": [
        "run",
        "--frozen",
        "--directory",
        "/path/to/open-wearables/mcp",
        "start"
      ]
    }
  }
}

Restart Claude Desktop. The agent now has access to all five tools.

Building the Reasoning Layer on Top

The MCP server provides data access. The reasoning layer is what you define on top of it.

Domain framing. The same workout data means different things in different contexts. Your system prompt defines which interpretation framework the model applies.
Metric selection. When a user asks "how am I doing?", the agent needs to decide which metrics to retrieve. Your prompt guides this selection based on your use case.
Thresholds and baselines. "Your sleep efficiency was 89%" means nothing without a reference point. Your prompting layer provides the reference: the user's baseline, clinical guidelines, or domain-specific targets.
Guardrails. Health data applications operate near clinical territory. Your prompt defines what the agent is allowed to conclude and what it defers to a professional.

MCP Server vs. Direct API Integration

The MCP server is the right choice for AI assistant interfaces (Claude Desktop, Cursor IDE), internal tooling where analysts query health data through a chat interface, and prototyping.

For production backend integrations, call the Open Wearables REST API directly from your backend. The REST API gives you full control over data retrieval, context construction, and model interaction.

            curl -H "X-API-Key: YOUR_API_KEY" \
  "http://localhost:8000/api/v1/users/USER_ID/events/workouts?start=2026-07-01&end=2026-07-22"

FAQ

Does the MCP server work with models other than Claude?

MCP support varies by model and interface. Claude Desktop and Cursor IDE have native MCP support. Other interfaces are adding support as the standard gains adoption. For model-agnostic integrations, use the Open Wearables REST API directly.

Can the agent query multiple users at once?

The get_users tool returns a list of users accessible via your API key. The agent can query data for any user in that list. Multi-user queries (comparing two users, team-level aggregations) require multiple tool calls or custom backend logic.

What is the timeseries tool's page limit and why does it exist?

The get_timeseries tool is capped at 100 pages per call (up to 10,000 samples). This prevents context overflow and protects the backend from expensive queries. For most questions about HRV, SpO2, or intraday heart rate, a bounded time window is more useful than raw full-resolution data.

Can I extend the MCP server with custom tools?

Yes. The MCP server is open source and uses FastMCP. You can add custom tools that expose additional data, perform domain-specific computations, or integrate external data sources. Custom toolsets are also part of the commercial services offered by Momentum for teams that need domain-specific health reasoning beyond what ships open source.

What is the present_health_data prompt and when should I use it?

It is a pre-built formatting prompt that instructs the model to present health data with context rather than as raw values. It covers unit conversions (meters to km), rounding rules, and presentation principles like leading with insights and highlighting patterns. You can invoke it in Claude Desktop by referencing it in your query.

Back to all posts