Overview

Let your AI agents read a user's health data directly over MCP, without building an API integration, handling webhooks, or storing and parsing data yourself.

Terra AI lets your AI agents interface with Terra's health data directly through an MCP (Model Context Protocol) server. The server gives your agent the tools and context it needs to query a user's data and reason over it.

Through Terra AI, your agent can:

1. Request only specific, relevant datasets

2. Access a user's health memory

3. Access aggregated stats, trends, and baselines

4. Access the semantic meaning of health data

Terra AI is not a tool for writing Terra code. Terra AI reads your users' health data at runtime. To help your coding agent write a Terra integration, install the Agent skills and the Terra CLI, which answers questions from these docs with terra ask.

Why we built Terra AI

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

You don't have to make API calls, handle webhooks, trigger backfills, or store and parse data. Your agent retrieves only meaningful, relevant data for reasoning, without overfetching or bloating its context window.

Quick install

Add the MCP configuration to your client to get started. Below are setup guides for some example AI IDEs, but you can use Terra AI with any system that supports MCP.

You need to include your dev-id and x-api-key in the HTTP headers. You can find these on the Terra 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

1. In Claude Desktop, navigate to Settings > Developer

2. Select Edit Config to open the configuration file

3. Paste the following into claude_desktop_config.json

{
  "mcpServers": {
    "terra": {
      "url": "https://access.tryterra.co/api/v2/mcp/<user_id>",
      "headers": {
        "dev-id": "YOUR_DEV_ID",
        "x-api-key": "YOUR_API_KEY"
      }
    }
  }
}

Cursor

1. Open Cursor, then navigate to Cursor Settings > Tools & Integrations

2. Select New MCP Server

3. Paste the following into mcp.json

{
  "mcpServers": {
    "terra": {
      "url": "https://access.tryterra.co/api/v2/mcp/<user_id>",
      "headers": {
        "dev-id": "YOUR_DEV_ID",
        "x-api-key": "YOUR_API_KEY"
      }
    }
  }
}

VS Code

1. Open VS Code, then open the configuration file by running MCP: Open User Configuration in the command palette

2. Paste the following into mcp.json

{
  "mcpServers": {
    "terra": {
      "url": "https://access.tryterra.co/api/v2/mcp/<user_id>",
      "headers": {
        "dev-id": "YOUR_DEV_ID",
        "x-api-key": "YOUR_API_KEY"
      }
    }
  }
}

Windsurf

1. Open Windsurf, then navigate to Windsurf Settings > Cascade > MCP servers

2. Select Manage MCP Servers

3. Select View raw config

4. Paste the following into mcp_config.json

{
  "mcpServers": {
    "terra": {
      "url": "https://access.tryterra.co/api/v2/mcp/<user_id>",
      "headers": {
        "dev-id": "YOUR_DEV_ID",
        "x-api-key": "YOUR_API_KEY"
      }
    }
  }
}

Replit

1. Open Replit, navigate to the 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/<user_id>

4. Add custom headers: your dev-id and your x-api-key

5. Select Test & Save

Available tools

Tools are functions your AI agent calls to get specific health data. They can query specific data and perform aggregations.

Each tool takes parameters such as user_id, a list of data fields, and optional filter conditions. For the full list of data fields available to each tool, see data models.

Tool	Purpose	Example fields
get_sleep_data	Sleep quality and quantity	Sleep start and end time, total sleep, REM, deep and light sleep, sleep latency, average and resting HR, average HRV, respiratory rate, average SpO2, sleep score
get_activity_data	Activity and workout sessions	Activity start and end time, activity type, location, active, inactive and rest time, intensity bands, total distance, step count, floors climbed, swimming laps
get_daily_data	Whole-day health summaries	Average, maximum, minimum and resting heart rate, average and minimum HRV, average SpO2, total and net active calories, activity time, daily distance and steps, stress duration, strain level, recovery and activity score
get_body_data	Body measurements	Water consumption, VO2 max estimate, average SpO2, blood pressure, measurements, temperature, ketones, ECG data
get_nutrition_data	Nutrients and calorie consumption	Total calories, protein, carbohydrates, total, trans and saturated fat, sugar, cholesterol, fiber, vitamins, micronutrients, amino acids
get_menstruation_data	Menstrual cycle and fertility	Cycle start and end time, period start date, current phase and its length, days until next phase, predicted and actual cycle length, fertility window start and end, predicted ovulation day

Example scenarios

Prompts your AI agent can answer once connected to Terra AI:

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 optimisation

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

• Find all days where I had a 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 AI includes

Terra AI's MCP server exposes three primitives:

1. Tools: functions your agent calls to get specific health data, and to perform aggregations. For example, the sleep tool can analyse a user's sleep architecture between 12 November 2025 and 30 November 2025.

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

3. Prompts: text-based templates that help your agent understand how to use the tools and retrieve data from the resources.

Next steps

• Error states covers what your agent sees when a call fails, and what is not guaranteed.