> For the complete documentation index, see [llms.txt](https://docs.tryterra.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tryterra.co/ai-interface/ai-interface.md). # 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](https://modelcontextprotocol.io) (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 {% hint style="info" %} **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](https://docs.tryterra.co/developer-tools/agent-skills) and the [Terra CLI](https://docs.tryterra.co/developer-tools/terra-cli/terra-cli), which answers questions from these docs with `terra ask`. {% endhint %} ## 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](https://dashboard.tryterra.co) 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: ```bash 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. 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** ```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. Paste the following into **mcp.json** ```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. Paste the following into **mcp.json** ```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. Paste the following into **mcp\_config.json** ```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 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/` 4. Add custom headers: your `dev-id` and your `x-api-key` 5. Select **Test & Save** {% endtab %} {% endtabs %} ## 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](https://docs.tryterra.co/reference/health-and-fitness-api/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](/ai-interface/error-states.md) covers what your agent sees when a call fails, and what is not guaranteed.