Terra AI

Our AI suite allows your AI agents to interface with Terra's health data directly. Your AI agents can do this through our MCP (Model Context Protocol) which gives your AI agent the necessary tools and data. Our MCP allows you to:

1. Request only specific, relevant data sets

2. Access a user’s health memory

3. Access aggregated stats, trends and baselines

4. Access semantic meaning of health data

Why we built Terra AI

We built Terra AI so that your AI agents can retrieve and reason over health data in the most token efficient way.

This means that you don't have to make API calls, handle webhooks, trigger backfills, store or parse data. It ensures that your agent only retrieves meaningful, relevant data for reasoning, without having to overfetch or bloat their context limits.

Quick install

You need to add the MCP configuration to your client to get started. Below is the setup guide for some example AI IDEs to test the responses you would get for example prompts, but you can use Terra's AI suite with any system that supports an MCP.

You will need to include your dev-id and x-api-key in the HTTP headers. You can find these on Terra's dashboard under API keys. The user_id is passed as part of the server URL.

Claude Code

In your terminal, run the following command:

claude mcp add --transport http terra-mcp https://access.tryterra.co/api/v2/mcp/<user_id> \
  --header "dev-id: <YOUR_DEV_ID>" \
  --header "x-api-key: <YOUR_API_KEY>"

Claude desktop

Cursor

VS code

Windsurf

Replit

Available tools

Tools are functions that your AI agent can call to get specific health data. They can be used to query specific data and perform aggregations.

Once connected, you can use the below tools. Each tool uses parameters such as user_id, list of data fields, and optional filter conditions. To see the full list of available data fields for each tool, visit our data models.

Tool	Purpose	Examples
get_sleep_data	Gets sleep data including quality and quantity of sleep	Sleep end time Sleep start time Total sleep REM sleep Deep sleep Light sleep Sleep latency Average HR Resting HR Average HRV Respiratory rate Average SpO2 Sleep score full list here
get_activity_data	Gets activity and workout session data	Activity start time Activity end time Activity type (running, cycling) Location Active time Inactive time Rest time Low intensity time Moderate intensity time Vigorous intensity time Total distance Step count Floors climbed Swimming laps full list here
get_daily_data	Gets health data summaries throughout a given day	Average heart rate Maximum heart rate Minimum heart rate Average HRV Minimum HRV Max heart rate Resting heart rate Average SpO2 Total calories burned Net active calories Activity time Daily distance Daily step count Total stress duration Activity stress duration Strain level Recovery score Activity score full list here
get_body_data	Gets body measurements	Water consumption VO2 max estimate Average SpO2 Blood pressure Measurements Temperature Ketones ECG data full list here
get_nutrition_data	Gets nutrients and calorie consumption	Total calories Protein CArbohydrates Total fat Trans fat Saturated fat Sugar Cholesterol Fiber Vitamins Micronutrients Amino Acids full list here
get_menstruation_data	Gets menstrual cycle and fertility data	Cycle start time Cycle end time Period start date Current phase Length of current phase Days until next phase Predicted cycle length Actual cycle length Fertility widnow start Fertility window end Predicted ovulation day full list here

Example scenarios

To help you understand how to use our MCP, here is a list of scenarios and prompts that your AI agent get respond to using Terra's MCP:

Health insights and analysis

• Give me a complete health snapshot: sleep, activity, stress, and recovery for this week

• Show me the relationship between my sleep quality and next-day performance

• What's my longest streak of days with at least 7 hours of sleep?

Pattern recognition and correlations

• Show me the correlation between my sleep latency and my stress level

• What's my average resting heart rate on days after poor sleep vs good sleep?

Training and recovery optimization

• What's my optimal recovery time between high-intensity workouts?

• Find all days where I had low recovery score but still did intense workouts

Predictive and proactive insights

• What's my predicted recovery time for tomorrow based on today's workout?

• Based on my HRV trends, should I train hard or take it easy today?

What Terra's MCP includes

Terra's MCP includes three primitives:

1. Tools: These are functions that your AI agent can call to get specific health data. They can be used to query specific data and perform aggregations. Example: The sleep tool can be used to perform an analysis of a user's sleep architecture between the 12th November 2025 and 30th November 2025.

2. Resources: These provide context about the available data and how the data schema is structured.

3. Prompts: These are text based templates that help your AI agent understand how to use the tools and how to get data from our resources.