> 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/developer-tools/mcp-server.md). # MCP server Connect Claude, ChatGPT, Cursor, or any MCP client to your Terra account. Connect your AI assistant to your Terra account. It can check and change your environments, providers, destinations, events, billing, and team. {% hint style="info" %} This server manages your Terra account. To give an agent your users' health data, use the [AI Interface](https://docs.tryterra.co/ai-interface). {% endhint %} ## Install If you use Claude Code, Codex, or Cursor, install the [Terra API plugin](/developer-tools/readme.md#install-the-plugin). It adds this server along with the Terra skills, and updates automatically. To add only the server, use the direct setup in each tab. {% tabs %} {% tab title="Claude" %} 1. Open **Customize > Connectors** and click **Add custom connector**. 2. Name it `Terra` and paste this as the remote MCP server URL: ``` https://access.tryterra.co/api/v3/admin/mcp ``` 3. Click **Add**, then **Connect** and sign in. {% endtab %} {% tab title="ChatGPT" %} 1. Turn on **Developer mode** in **Settings > Apps > Advanced settings**. 2. Click **Create app** and fill in: * **Name:** `Terra` * **MCP server URL:** `https://access.tryterra.co/api/v3/admin/mcp` * **Authentication:** OAuth 3. Click **Create** and sign in. {% endtab %} {% tab title="Claude Code" %} **Plugin (recommended)** Run these commands in Claude Code: ``` /plugin marketplace add tryterra/agent-skills /plugin install terra@terra ``` Then run `/mcp` and pick the Terra server to sign in. **Direct** Run this in your terminal: ```bash claude mcp add --transport http terra https://access.tryterra.co/api/v3/admin/mcp ``` Then run `/mcp` in Claude Code and pick `terra` to sign in. {% endtab %} {% tab title="Codex" %} **Plugin (recommended)** Run this in your terminal: ```bash npx plugins add tryterra/agent-skills ``` Codex asks you to sign in the first time it connects. **Direct** Run this in your terminal: ```bash codex mcp add terra --url https://access.tryterra.co/api/v3/admin/mcp ``` Codex opens your browser to sign in. If it does not, run `codex mcp login terra`. {% endtab %} {% tab title="Cursor" %} **Plugin (recommended)** Run this in your project: ```bash npx plugins add tryterra/agent-skills ``` Cursor asks you to sign in the first time it connects. **Direct** Add this to `.cursor/mcp.json`: ```json { "mcpServers": { "terra": { "url": "https://access.tryterra.co/api/v3/admin/mcp" } } } ``` Cursor asks you to sign in the first time it connects. {% endtab %} {% tab title="VS Code" %} Add this to `.vscode/mcp.json`: ```json { "servers": { "terra": { "type": "http", "url": "https://access.tryterra.co/api/v3/admin/mcp" } } } ``` VS Code asks you to sign in the first time it connects. {% endtab %} {% tab title="Other clients" %} Add a remote MCP server with this URL: ``` https://access.tryterra.co/api/v3/admin/mcp ``` Any client that supports remote MCP servers over Streamable HTTP with OAuth works. Clients identify themselves with a client ID metadata document. Dynamic client registration is not supported. {% endtab %} {% endtabs %} ## Sign in Connecting opens the Terra dashboard. Choose what the assistant can do: | Access | Can | Cannot | | --------- | ----------------------------------------------------------- | ---------------------------------------------------------- | | MCP | Read everything, change integration settings, resend events | Spend money, remove people, issue credentials, rotate keys | | Read only | Read everything except API keys and payload bodies | Change anything | You can also limit access to specific environments. Access lasts 30 days. Revoke it from the dashboard at any time. ## Tools Most areas have a read tool and a write tool. Your assistant only sees the tools your access allows. | Resource | Tool | Description | | ------------- | -------------------------------- | -------------------------------------------------------------------- | | Account | `account_retrieve` | Show the signed-in token and user | | | `account_update` | Update your user profile | | | `company_retrieve` | Show your company summary | | | `company_update` | Update your company profile | | | `entitlements_list` | List the features your company can use | | Environments | `environments_read` | List environments, read their details and API key | | | `environments_write` | Rename an environment or rotate its API key | | Providers | `unified_api_sources_read` | List enabled providers, their OAuth credentials and scopes | | | `unified_api_sources_write` | Enable or disable providers, set custom OAuth credentials and scopes | | Destinations | `unified_api_destinations_read` | List destinations and Supabase projects | | | `unified_api_destinations_write` | Create, update, or delete destinations, and connect Supabase | | Data settings | `unified_api_data_read` | Read the processing type and which fields each data type returns | | | `unified_api_data_write` | Change the processing type and field selection | | | `unified_api_widget_retrieve` | Read the widget configuration | | | `unified_api_widget_update` | Replace the widget configuration | | Users | `users_read` | List user connections and connection statistics | | Events | `events_read` | List deliveries, read an event or its payload, delivery statistics | | | `events_write` | Resend an event or generate a test event | | Scores | `unified_api_scores_read` | Read score settings, history, and analytics | | | `unified_api_scores_update` | Turn a score on or off, or change its weights | | Models | `models_read` | List the model catalogue and past model runs | | Workouts | `workouts_metadata_read` | Read custom fields on workouts | | | `workouts_metadata_write` | Set or delete custom fields on a workout | | Vantage | `vantage_api_version_retrieve` | Read the Vantage API version | | | `vantage_api_version_update` | Change the Vantage API version | | Data tokens | `data_tokens_read` | List data tokens and reveal a token's secret | | | `data_tokens_write` | Create or revoke data tokens | | Access tokens | `tokens_list` | List your account's personal access tokens | | | `tokens_delete` | Revoke a personal access token | | Billing | `billing_read` | Read subscriptions, invoices, payment method, and usage | | | `billing_write` | Change your plan, pay invoices, and set invoice details | | Team | `team_read` | List team members and invitations | | | `team_write` | Invite, update, or remove team members | | Docs | `docs_ask` | Ask the Terra docs a question | ## Approvals Some changes need your approval in the dashboard, such as paying an invoice, rotating an API key, or removing a team member. The assistant gives you a link. Approve it, and the change runs once. Any change can be previewed first with `dry_run`, without approval. ## Things to ask ``` Which providers are enabled in production, and where do webhooks go? ``` ``` A sleep webhook never arrived for user 8f2a1c. Find out why and resend it. ``` ``` Point my staging webhooks at https://example.com/hook. ``` ## Security * **Grant the least access you need.** Use Read only to explore, and limit access to the environments you are working in. * **Review changes before approving them.** Assistants can be misled by text inside the data they read, such as a webhook payload. * **The MCP access level can read API keys.** Results go to your AI provider, so choose Read only if that is a concern.