Thryve MCP Server

Stateless MCP server that exposes Thryve's health data API via HTTP. Designed for the BlueNexus MCP proxy—clients access wearable data without handling credentials.

Quick Start

pnpm install
pnpm run build
pnpm start  # Listens on http://localhost:30000

Scripts:

• pnpm run build – Compile TypeScript
• pnpm run dev – Development mode with auto-reload (uses nodemon)
• pnpm run dev:debug – Development mode with DEBUG logging enabled
• pnpm start – Launch server

Configuration

Stateless design: all credentials arrive as HTTP headers from the BlueNexus MCP proxy.

| Header | Purpose | |--------|---------| | X-Thryve-Authentication-Token | User access token | | X-Thryve-Authorization | Thryve API Basic Auth | | X-Thryve-App-Authorization | Thryve app Basic Auth |

Development Features

Debug Mode

Enable detailed execution logging by setting the DEBUG environment variable:

DEBUG=true pnpm start
# or
pnpm run dev:debug

When debug mode is enabled, all tool responses include additional metadata:

{
  "data": { /* normal response data */ },
  "debug": {
    "toolName": "GetActivityData",
    "toolInput": { "timeSeries": "daily", "startTimestamp": "..." },
    "toolCallTime": 123.45,
    "timestamp": "2025-01-12T10:30:00.000Z"
  }
}

Debug Metadata:

• toolName – Name of the tool that was executed
• toolInput – Complete input arguments passed to the tool
• toolCallTime – Execution time in milliseconds
• timestamp – ISO 8601 timestamp of when the tool was called

This is useful for:

• Performance profiling and optimization
• Debugging tool execution flow
• Monitoring API response times
• Development and testing

Development Mode with Auto-Reload

The server uses nodemon to automatically reload when source files change:

pnpm run dev        # Watch and reload on changes
pnpm run dev:debug  # Watch with DEBUG mode enabled

Watched files:

• src/**/*.ts – All TypeScript source files
• tools.json – Dynamic tool definitions

Changes trigger automatic rebuild and server restart with a 1-second delay to prevent rapid restarts.

Dynamic Tool Loading

Tools can be defined in tools.json and are automatically loaded at startup. This allows for:

• Adding new tools without modifying core server code
• Easier tool management and organization
• Runtime tool configuration

The tool registry system (src/tool-registry.ts) maintains all tool definitions, schemas, and handlers in a centralized location.

Endpoints

• GET /health – Service status and version
• POST /mcp – JSON-RPC endpoint for MCP protocol

Tools

Category-Specific Tools (16 tools)

Each tool retrieves data for one health category. All support daily/epoch resolution.

Available Tools:

• GetActivityData – Steps, distance, calories, elevation
• GetHeartRateData – Resting, average, min, max heart rate
• GetSleepData – Duration, stages, quality metrics
• GetWorkoutsData – Exercise sessions, performance
• GetStressAndHRVData – Stress levels, HRV metrics
• GetRespiratoryData – Breathing rate, SpO2
• GetBloodGlucoseData – Glucose levels, CGM data
• GetBodyCompositionData – Weight, BMI, body fat
• GetWomensHealthData – Menstrual cycle, ovulation
• GetNutritionData – Calories, macros, water
• GetCardiovascularData – Blood pressure, VO2 max (aggregates 2 sub-categories)
• GetWellnessData – Mindfulness, recovery scores
• GetAudioAndHearingData – Environmental sound
• GetMicrobiomeData – Gut health metrics
• GetLocationData – GPS, routes, distance
• GetMovementAnalysisData – Gait, posture, biomechanics

Parameters (all tools):

• timeSeries – "daily" | "epoch" (default: "daily")
• startTimestamp – ISO 8601 (defaults to 7 days ago)
• endTimestamp – ISO 8601 (defaults to now)
• dataSources – Array of data source identifiers (e.g., ["Fitbit", "Garmin", "AppleHealth"])
• limit – Max records to return
• includedData – Array of category-specific data type names to return (falls back to all data types when omitted)

Example:

curl -X POST http://localhost:30000/mcp \
  -H "Content-Type: application/json" \
  -H "X-Thryve-Authentication-Token: your-token" \
  -H "X-Thryve-Authorization: Basic your-auth" \
  -H "X-Thryve-App-Authorization: Basic your-app-auth" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "GetActivityData",
      "arguments": {
        "timeSeries": "daily",
        "startTimestamp": "2025-10-21T00:00:00Z",
        "endTimestamp": "2025-10-28T23:59:59Z",
        "dataSources": ["Fitbit"],
        "includedData": ["Steps", "BurnedCalories"]
      }
    }
  }'

Data source identifiers

Category tools, searchKeyword, and searchFilters now accept friendly source names instead of numeric IDs. Use listConnectedSources to discover what each user has linked, or pick from common values:

• Fitbit
• Garmin
• Polar
• AppleHealth
• SamsungHealth
• Withings
• Strava
• Oura
• Whoop
• GoogleFitREST
• GoogleFitNative
• HealthConnect
• Dexcom
• Suunto

Search and Retrieval Tools

searchKeyword

Search for health data by property name (e.g., "SleepBinary", "Steps", "HeartRate").

Parameters:

• query (required) – Property name to search
• startDate – YYYY-MM-DD
• endDate – YYYY-MM-DD
• dataType – Filter by category
• dataSource – Filter by source identifier (e.g., "Fitbit")
• page – Page number (default: 1)
• pageSize – Results per page (default: 50, max: 200)
• sortBy – "timestamp" | "day" | "value" | "dataType" | "dataSource"
• sortOrder – "asc" | "desc"

searchFilters

Advanced search with comprehensive filtering. Replaces legacy getDailyData/getEpochData.

Parameters:

• timeSeries – "daily" | "epoch" | "both" (default: "both")
• dataTypes – Array of data type IDs
• dataSources – Array of source identifiers
• categories – Array of category names
• groupByCategory – Boolean (default: false)
• limit – Max records
• startDate / endDate – YYYY-MM-DD
• startTimestamp / endTimestamp – ISO 8601
• valueMin / valueMax – Value range
• page / pageSize – Pagination
• sortBy / sortOrder – Sorting

Example (grouped by category):

{
  "name": "searchFilters",
  "arguments": {
    "timeSeries": "daily",
    "categories": ["Activity", "Heart Rate"],
    "groupByCategory": true
  }
}

Information Tools

listConnectedSources

List all connected data sources (wearables, apps).

Parameters: None

Response:

{
  "sources": [
    {
      "dataSource": 1,
      "connectedAt": "2025-06-02T00:00:00Z"
    }
  ],
  "count": 1
}

listDevices

List all connected devices.

Parameters: None

Response:

{
  "devices": [
    {
      "dataSource": 1,
      "deviceName": "Versa 3",
      "connectedAt": "2025-06-02T00:00:00Z"
    }
  ],
  "count": 1
}

getAvailableDataTypes

Catalog of 250+ data types organized by 16 categories.

Parameters:

• category – Filter by category name
• search – Keyword search (e.g., "calories")
• dataSource – Filter by brand (e.g., "Fitbit")

Response (no filters):

{
  "categories": [
    {
      "category": "Activity",
      "description": "Steps, distance, calories...",
      "dataTypeCount": 42,
      "thryveCategories": ["Activity"]
    }
  ],
  "totalCategories": 16,
  "totalDataTypes": 250
}

Response (with category filter):

{
  "category": "Activity",
  "count": 42,
  "dataTypes": [
    {
      "id": 1000,
      "name": "Steps",
      "thryveCategory": "Activity",
      "temporalResolution": "Both",
      "unit": "count",
      "supportedSources": ["Fitbit", "Garmin", "AppleHealth"]
    }
  ]
}

Common Data Source Identifiers

• Fitbit
• Garmin
• Polar
• AppleHealth
• SamsungHealth
• Withings
• Strava
• Oura
• Whoop
• Dexcom

Error Handling

• Validation errors – Zod schemas return descriptive messages
• API errors – Propagates Thryve response codes
• Network errors – Surfaced with context for retry logic