MCP Tools Reference

Comprehensive reference for all 47 Model Context Protocol (MCP) tools provided by Pierre Fitness Platform. These tools enable AI assistants to access fitness data, analyze performance, manage configurations, and provide personalized recommendations.

Overview

Pierre MCP Server provides tools organized into 8 functional categories:

• Core Fitness Tools: Activity data and provider connections
• Goals & Planning: Goal setting and progress tracking
• Performance Analysis: Activity insights and trend analysis
• Configuration Management: System-wide configuration
• Fitness Configuration: User fitness zones and thresholds
• Sleep & Recovery: Sleep analysis and recovery tracking
• Nutrition: Dietary calculations and USDA food database
• Recipe Management: Training-aware meal planning and recipe storage

Output Format

Most data-returning tools support an optional format parameter:

• json (default): Standard JSON output
• toon: Token-Oriented Object Notation for ~40% fewer LLM tokens

Use format: "toon" when querying large datasets (year summaries, batch analysis) to reduce LLM context usage.

Core Fitness Tools

Basic fitness data retrieval and provider connection management.

Parameter Details

Supported Providers: strava, garmin, fitbit, whoop, terra

get_activities Parameters:

• provider: Fitness provider name (e.g., ‘strava’, ‘garmin’, ‘fitbit’, ‘whoop’, ‘terra’)
• limit: Maximum number of activities to return
• offset: Number of activities to skip (for pagination)

get_connection_status Parameters:

• strava_client_id: Your Strava OAuth client ID (uses server defaults if not provided)
• strava_client_secret: Your Strava OAuth client secret
• fitbit_client_id: Your Fitbit OAuth client ID (uses server defaults if not provided)
• fitbit_client_secret: Your Fitbit OAuth client secret

Goals & Planning

Tools for setting fitness goals, tracking progress, and receiving AI-powered goal suggestions.

Parameter Details

set_goal Parameters:

• goal_type: Type of goal - distance, time, frequency, performance, or custom
• target_date: Target completion date in ISO format (e.g., “2025-12-31”)

suggest_goals Parameters:

• goal_category: Category of goals - distance, performance, consistency, or all

Performance Analysis

Advanced analytics tools for activity analysis, trend detection, and performance predictions.

Parameter Details

get_activity_intelligence Parameters:

• include_weather: Whether to include weather analysis (default: true)
• include_location: Whether to include location intelligence (default: true)

calculate_metrics Parameters:

• metrics: Array of specific metrics to calculate (e.g., ['trimp', 'power_to_weight', 'efficiency'])

analyze_performance_trends Parameters:

• timeframe: Time period - week, month, quarter, sixmonths, or year
• metric: Metric to analyze - pace, heart_rate, power, distance, or duration

compare_activities Parameters:

• comparison_type: Type of comparison - similar_activities, personal_best, average, or recent

detect_patterns Parameters:

• pattern_type: Pattern to detect - training_consistency, seasonal_trends, performance_plateaus, or injury_risk

generate_recommendations Parameters:

• recommendation_type: Type of recommendations - training, recovery, nutrition, equipment, or all

calculate_fitness_score Parameters (Cross-Provider Support):

• timeframe: Analysis period - month, last_90_days, or all_time
• sleep_provider: Optional sleep/recovery provider for cross-provider analysis (e.g., whoop, garmin). When specified, recovery quality factors into the fitness score:
  • Excellent recovery (90-100): +5% fitness score bonus
  • Good recovery (70-89): No adjustment
  • Moderate recovery (50-69): -5% penalty
  • Poor recovery (<50): -10% penalty

analyze_training_load Parameters (Cross-Provider Support):

• timeframe: Analysis period - week, month, etc.
• sleep_provider: Optional sleep/recovery provider for cross-provider analysis. Adds recovery context to training load analysis including sleep quality score, HRV data, and recovery status.

Configuration Management

System-wide configuration management tools for physiological parameters and training zones.

Parameter Details

update_user_configuration Parameters:

• profile: Configuration profile to apply (e.g., ‘Research’, ‘Elite’, ‘Recreational’, ‘Beginner’, ‘Medical’)
• parameters: Parameter overrides as JSON object

calculate_personalized_zones Parameters:

• vo2_max: VO2 max in ml/kg/min
• resting_hr: Resting heart rate in bpm (default: 60)
• max_hr: Maximum heart rate in bpm (default: 190)
• lactate_threshold: Lactate threshold as percentage of VO2 max (default: 0.85)
• sport_efficiency: Sport efficiency factor (default: 1.0)

Fitness Configuration

User-specific fitness configuration for heart rate zones, power zones, and training thresholds.

Parameter Details

get_fitness_config / set_fitness_config Parameters:

• configuration_name: Name of the configuration (defaults to ‘default’)
• configuration: Fitness configuration object containing zones, thresholds, and training parameters

Configuration Object Structure:

{
  "heart_rate_zones": {
    "zone1": {"min": 100, "max": 120},
    "zone2": {"min": 120, "max": 140},
    "zone3": {"min": 140, "max": 160},
    "zone4": {"min": 160, "max": 180},
    "zone5": {"min": 180, "max": 200}
  },
  "power_zones": { /* similar structure */ },
  "ftp": 250,
  "lthr": 165,
  "max_hr": 190,
  "resting_hr": 50,
  "weight_kg": 70
}

Sleep & Recovery

Sleep quality analysis and recovery monitoring tools using NSF/AASM guidelines. These tools support cross-provider data fetching, allowing you to use activities from one provider and sleep/recovery data from another.

Cross-Provider Support

Sleep and recovery tools support fetching data from different providers for activities and sleep. This enables scenarios like:

• Strava + WHOOP: Activities from Strava, recovery/sleep data from WHOOP
• Garmin + Fitbit: Running data from Garmin, sleep tracking from Fitbit
• Any activity provider + Any sleep provider: Mix and match based on your device ecosystem

Provider Priority (when auto-selecting):

• Activity providers: strava > garmin > fitbit > whoop > terra > synthetic
• Sleep providers: whoop > garmin > fitbit > terra > synthetic

Example: Cross-Provider Recovery Score:

{
  "tool": "calculate_recovery_score",
  "parameters": {
    "activity_provider": "strava",
    "sleep_provider": "whoop"
  }
}

Response includes providers used:

{
  "recovery_score": { ... },
  "providers_used": {
    "activity_provider": "strava",
    "sleep_provider": "whoop"
  }
}

Parameter Details

analyze_sleep_quality Sleep Data Object (for manual input mode):

{
  "date": "2025-11-28",
  "duration_hours": 7.5,
  "efficiency_percent": 85,
  "deep_sleep_hours": 1.5,
  "rem_sleep_hours": 2.0,
  "light_sleep_hours": 4.0,
  "awakenings": 2,
  "hrv_rmssd_ms": 45
}

calculate_recovery_score / optimize_sleep_schedule User Config:

{
  "ftp": 250,
  "lthr": 165,
  "max_hr": 190,
  "resting_hr": 50,
  "weight_kg": 70
}

track_sleep_trends Parameters:

• sleep_history: Array of sleep data objects (minimum 7 days required)
• sleep_provider: Provider name to fetch sleep history from (alternative to sleep_history)
• days_back: Number of days to analyze (default: 14)

optimize_sleep_schedule Parameters:

• activity_provider: Provider for activity data
• sleep_provider: Provider for sleep data (optional, can be same as activity_provider)
• target_sleep_hours: Target sleep duration in hours (default: 8.0)
• training_schedule: Weekly training schedule object

Nutrition

Nutrition calculation tools with USDA FoodData Central database integration.

Parameter Details

calculate_daily_nutrition Parameters:

• gender: Either male or female
• activity_level: sedentary, lightly_active, moderately_active, very_active, or extra_active
• training_goal: maintenance, weight_loss, muscle_gain, or endurance_performance
• age: Age in years (max 150)

get_nutrient_timing Parameters:

• workout_intensity: Workout intensity level - low, moderate, or high (required if activity_provider not specified)
• activity_provider: Fitness provider for activity data (e.g., strava, garmin). When specified, workout intensity is auto-inferred from recent training load
• days_back: Number of days of activity history to analyze for intensity inference (default: 7, max: 30)

Cross-Provider Support: When using activity_provider, the tool analyzes your recent training data to automatically determine workout intensity based on training volume and heart rate patterns:

• High intensity: >2 hours/day or average HR >150 bpm
• Moderate intensity: 1-2 hours/day or average HR 130-150 bpm
• Low intensity: <1 hour/day and average HR <130 bpm

search_food Parameters:

• query: Food name or description to search for
• page_size: Number of results to return (default: 10, max: 200)

get_food_details Parameters:

• fdc_id: USDA FoodData Central ID (obtained from search_food results)

analyze_meal_nutrition Foods Array:

{
  "foods": [
    {"fdc_id": 171705, "grams": 100},
    {"fdc_id": 173424, "grams": 50}
  ]
}

Usage Examples

Connecting to a Provider

{
  "tool": "connect_provider",
  "parameters": {
    "provider": "strava"
  }
}

Getting Recent Activities

{
  "tool": "get_activities",
  "parameters": {
    "provider": "strava",
    "limit": 10,
    "offset": 0
  }
}

Analyzing Activity Intelligence

{
  "tool": "get_activity_intelligence",
  "parameters": {
    "provider": "strava",
    "activity_id": "12345678",
    "include_weather": true,
    "include_location": true
  }
}

Setting a Fitness Goal

{
  "tool": "set_goal",
  "parameters": {
    "title": "Run 100km this month",
    "goal_type": "distance",
    "target_value": 100000,
    "target_date": "2025-12-31",
    "sport_type": "Run"
  }
}

Calculating Daily Nutrition

{
  "tool": "calculate_daily_nutrition",
  "parameters": {
    "weight_kg": 70,
    "height_cm": 175,
    "age": 30,
    "gender": "male",
    "activity_level": "very_active",
    "training_goal": "endurance_performance"
  }
}

Analyzing Sleep Quality

Using a sleep provider (recommended):

{
  "tool": "analyze_sleep_quality",
  "parameters": {
    "sleep_provider": "whoop",
    "days_back": 7
  }
}

Cross-provider analysis (activities from Strava, sleep from WHOOP):

{
  "tool": "analyze_sleep_quality",
  "parameters": {
    "activity_provider": "strava",
    "sleep_provider": "whoop"
  }
}

Manual sleep data input (for providers without direct integration):

{
  "tool": "analyze_sleep_quality",
  "parameters": {
    "sleep_data": {
      "date": "2025-11-28",
      "duration_hours": 7.5,
      "efficiency_percent": 85,
      "deep_sleep_hours": 1.5,
      "rem_sleep_hours": 2.0,
      "light_sleep_hours": 4.0,
      "awakenings": 2,
      "hrv_rmssd_ms": 45
    }
  }
}

Recipe Management

Training-aware recipe management tools for meal planning aligned with workout schedules. Uses the “Combat des Chefs” architecture where LLM clients generate recipes and Pierre validates nutrition via USDA.

Parameter Details

Meal Timing Values:

• pre_training: High-carb focus (55% carbs, 20% protein, 25% fat)
• post_training: High-protein focus (45% carbs, 30% protein, 25% fat)
• rest_day: Lower carb, moderate protein (35% carbs, 30% protein, 35% fat)
• general: Balanced macros (45% carbs, 25% protein, 30% fat)

Ingredient Object Structure:

{
  "name": "chicken breast",
  "amount": 200,
  "unit": "grams",
  "preparation": "grilled"
}

Supported Units (auto-converted to grams):

• Weight: grams, g, oz, ounces, lb, pounds, kg
• Volume: ml, milliliters, cups, cup, tbsp, tablespoon, tsp, teaspoon
• Count: pieces, piece, whole

Skill Level Values: beginner, intermediate, advanced

Dietary Restrictions: vegetarian, vegan, gluten_free, dairy_free, nut_free, keto, paleo

Example: Validate a Post-Workout Recipe:

{
  "tool": "validate_recipe",
  "parameters": {
    "servings": 1,
    "meal_timing": "post_training",
    "target_calories": 600,
    "ingredients": [
      {"name": "chicken breast", "amount": 200, "unit": "grams"},
      {"name": "brown rice", "amount": 1, "unit": "cup"},
      {"name": "broccoli", "amount": 150, "unit": "grams"}
    ]
  }
}

Example: Save a Recipe:

{
  "tool": "save_recipe",
  "parameters": {
    "name": "Recovery Shake",
    "servings": 1,
    "meal_timing": "post_training",
    "description": "Quick protein shake for post-workout recovery",
    "prep_time_mins": 5,
    "ingredients": [
      {"name": "whey protein powder", "amount": 30, "unit": "grams"},
      {"name": "banana", "amount": 1, "unit": "piece"},
      {"name": "almond milk", "amount": 1, "unit": "cup"}
    ],
    "instructions": ["Add all ingredients to blender", "Blend until smooth"],
    "tags": ["quick", "shake", "high-protein"]
  }
}

Tool Selection & Administration

Pierre MCP Server supports per-tenant tool selection, allowing administrators to control which tools are available to each tenant based on subscription plans and custom overrides.

Overview

Tools are organized into 8 categories and gated by subscription plan tiers:

How Tool Selection Works

When an MCP client calls a tool, the server checks:

1. Plan Restriction - Does tenant’s plan meet the tool’s min_plan requirement?
2. Tenant Override - Is there a custom override for this tenant/tool?
3. Catalog Default - Fall back to the tool’s default enablement

If a tool is disabled, the server returns:

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32601,
    "message": "Tool 'X' is not available for your tenant. Contact your administrator to enable it."
  }
}

Tool Categories by Plan Tier

Starter Plan (Default):

• Core Fitness: get_activities, get_athlete, get_stats, connect_provider, disconnect_provider, get_connection_status
• Configuration: get_user_profile, set_preferences, get_system_config
• Connections: OAuth management tools

Professional Plan:

• All Starter tools, plus:
• Performance Analysis: analyze_activity, analyze_performance_trends, calculate_training_load
• Goals: set_goal, suggest_goals, track_progress
• Nutrition: calculate_nutrition, search_usda_foods
• Sleep: analyze_sleep, get_sleep_metrics
• Recipes: create_recipe, validate_recipe

Enterprise Plan:

• All Professional tools, plus:
• Advanced AI: get_activity_intelligence, predict_performance
• Premium Analytics: calculate_fitness_score, detect_patterns

Tenant Overrides

Administrators can customize tool availability per tenant:

• Enable tools above plan level (e.g., beta testing)
• Disable specific tools for compliance/policy reasons
• Each override records the admin who made the change and optional reason

Overrides are stored in tenant_tool_overrides table and cached for performance (5-minute TTL).

Integration Notes

• Unknown Tools: Tools not in the catalog (plugins) pass through by default
• Caching: Effective tool lists are cached per tenant (LRU, 1000 tenants max)
• Cache Invalidation: Automatic on override changes

Notes

• Authentication: Most tools require OAuth authentication with Pierre and the respective fitness provider
• Provider Support: Supports Strava, Garmin, Fitbit, WHOOP, and Terra (150+ wearables) providers
• Rate Limits: Subject to provider API rate limits (e.g., Strava: 100 requests per 15 minutes, 1000 per day)
• Token Refresh: OAuth tokens are automatically refreshed when expired
• USDA Database: Food search tools use free USDA FoodData Central API with 24-hour caching
• Scientific Guidelines:
  • Sleep analysis follows NSF (National Sleep Foundation) and AASM (American Academy of Sleep Medicine) guidelines
  • Nutrition recommendations follow ISSN (International Society of Sports Nutrition) guidelines
  • BMR calculations use validated Mifflin-St Jeor formula

Tool Categories Summary

Additional Resources

• MCP Protocol Specification
• Pierre MCP Server Repository
• Development Guide
• Testing Guide
• Configuration Guide

Last Updated: 2025-12-06 Pierre Fitness Platform v1.0.0