# 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. {% tabs %} {% tab title="Claude Code" %} In your terminal, run the following command: ``` claude mcp add --transport http terra-mcp https://access.tryterra.co/api/v2/mcp/ \ --header "dev-id: " \ --header "x-api-key: " ``` {% endtab %} {% tab title="Claude desktop" %} 1. On Claude Dektop, navigate to **Settings > Developer** 2. Select **Edit Config** to open the configuration file 3. Copy paste the following code snippet to update the **claude\_desktop\_config.json** ``` { "mcpServers": { "terra": { "url": "https://access.tryterra.co/api/v2/mcp/", "headers": { "dev-id": "YOUR_DEV_ID", "x-api-key": "YOUR_API_KEY" } } } } ``` {% endtab %} {% tab title="Cursor" %} 1. Open Cursor, then navigate to **Cursor Settings** > **Tools & Integrations** 2. Select **New MCP Server** 3. Copy paste the following code snippet to update the **mcp.json** ``` { "mcpServers": { "terra": { "url": "https://access.tryterra.co/api/v2/mcp/", "headers": { "dev-id": "YOUR_DEV_ID", "x-api-key": "YOUR_API_KEY" } } } } ``` {% endtab %} {% tab title="VS code" %} 1. Open VS Code, then open the configuration file by running `MCP: Open User Configuration` in the command palette. 2. Copy paste the following code snippet to update the **mcp.json** ``` { "mcpServers": { "terra": { "url": "https://access.tryterra.co/api/v2/mcp/", "headers": { "dev-id": "YOUR_DEV_ID", "x-api-key": "YOUR_API_KEY" } } } } ``` {% endtab %} {% tab title="Windsurf" %} 1. Open Windsurf, then navigate to **Windsurf Settings** > **Cascade** > **MCP servers** 2. Select **Manage MCP Servers** 3. Select **View raw config** 4. Copy paste the following code snippet to update the **mcp\_config.json** ``` { "mcpServers": { "terra": { "url": "https://access.tryterra.co/api/v2/mcp/", "headers": { "dev-id": "YOUR_DEV_ID", "x-api-key": "YOUR_API_KEY" } } } ``` {% endtab %} {% tab title="Replit" %} 1. Open Replit, navigate to **Integrations page**, and scroll down to MCP Servers for **Replit Agent** 2. Select **Add MCP server** 3. Enter the server URL `https://access.tryterra.co/api/v2/mcp/` 4. Add customer headers: `your dev-id` and your `x-api-key` 5. Select **Test & Save** {% endtab %} {% endtabs %} ### 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](https://app.gitbook.com/s/eJJpVMsUARUJq9lYmL6t/health-and-fitness-api/data-models).
ToolPurposeExamples
get_sleep_dataGets 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_dataGets 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_dataGets 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.