# Install (https://terac.com/docs/researchers/mcp/install)

Connect the Terac MCP server to Claude, Claude Code, Cursor, VS Code, ChatGPT, or any MCP client.

This guide connects the Terac MCP server to your AI assistant so it can price, launch, and manage research on your behalf. Pick your client below; setup takes a couple of minutes.

## Prerequisites [#prerequisites]

Before connecting, make sure you have:

1. **A Terac account and organization**

   [Sign in to Terac](https://terac.com) and [create your organization](https://terac.com/docs/researchers/getting-started/create-organization) if you have not already. The MCP acts on behalf of a single organization.

   Connecting through the Claude or ChatGPT directory listing is the exception: if you have no organization yet, it walks you through creating one and then returns you to finish connecting.

2. **A way to authenticate**

   The server accepts two methods, and you only need one:

   * **API key** (recommended) is a single secret you paste into your client config. It works in every client, including headless and CI environments. [Generate one](https://terac.com/docs/researchers/integrations/api-keys) under your organization's **Settings → API Keys**. Keys start with `tk_`.
   * **OAuth** is a browser-based login with no key to manage. It is supported by clients that implement the MCP OAuth flow (Claude, Claude Code, Cursor, VS Code, ChatGPT). Your client opens a browser, you sign in, and you are done.

> Not sure which to use? Start with an **API key**. It is the most portable
> option and the only one that works for automation and CI.

## The Server Endpoint [#the-server-endpoint]

Every client below connects to the same URL:

`https://terac.com/api/mcp`

## Connect Your Client [#connect-your-client]

### Claude

Terac is published in the Claude directory, so there is no server URL to paste.

1. **Open the Terac app**

   Go to [Terac in the Claude directory](https://claude.ai/directory/terac), or search Claude's directory for **Terac**.

2. **Connect your account**

   Choose to connect and complete the sign-in when prompted. If you do not have a Terac organization yet, you can create one during this step and you will be returned to finish connecting.

3. **Pick your organization**

   Terac asks which organization the app should act on behalf of. That choice is remembered, and everything the app does afterwards is scoped to it.

Terac's tools are now available in the chat. Try asking: *"Use Terac to get my organization context."*

> The same listing covers Claude Desktop and Claude on the web. Prefer to wire
> up the raw MCP server instead? Add `https://terac.com/api/mcp` as a custom
> connector under **Settings → Connectors → Add custom connector**, or use the
> **Other (mcp-remote)** tab. Both reach the same server; the directory listing
> is simply fewer steps.

To use an API key instead, or on a build without the connector UI, open **Settings → Developer → Edit Config** and bridge through `mcp-remote`:

```json title="claude_desktop_config.json"
{
  "mcpServers": {
    "terac": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://terac.com/api/mcp",
        "--header",
        "x-api-key:tk_your_api_key"
      ]
    }
  }
}
```

Restart Claude Desktop after saving.

### Claude Code

The fastest path is the CLI. Run this from any project, or add `--scope user` to make it available everywhere:

```bash title="Add with an API key"
claude mcp add --transport http terac https://terac.com/api/mcp \
  --header "x-api-key: tk_your_api_key"
```

Prefer browser login? Omit the header and authenticate with OAuth instead:

```bash title="Add with OAuth"
claude mcp add --transport http terac https://terac.com/api/mcp
```

Then run `/mcp` inside Claude Code and select **terac** to complete the sign-in.

To share the server with your team, add it with `--scope project`, which writes a committed `.mcp.json`:

```json title=".mcp.json"
{
  "mcpServers": {
    "terac": {
      "type": "http",
      "url": "https://terac.com/api/mcp",
      "headers": {
        "x-api-key": "${TERAC_API_KEY}"
      }
    }
  }
}
```

Reference `${TERAC_API_KEY}` so the secret stays in your environment, not in the committed file.

### Cursor

Create or edit `~/.cursor/mcp.json` for all projects, or `.cursor/mcp.json` inside a single project:

```json title="~/.cursor/mcp.json"
{
  "mcpServers": {
    "terac": {
      "url": "https://terac.com/api/mcp",
      "headers": {
        "x-api-key": "tk_your_api_key"
      }
    }
  }
}
```

To keep the key out of the file, reference an environment variable instead: `"x-api-key": "${env:TERAC_API_KEY}"`.

Prefer OAuth? Drop the `headers` block and leave only the `url`. Cursor opens a browser to sign in the first time the server is used. Then open **Settings → MCP** and confirm **terac** shows a green dot.

### VS Code

With GitHub Copilot's agent mode, create `.vscode/mcp.json` in your workspace. The `inputs` block prompts for your key once and stores it securely instead of writing it to disk:

```json title=".vscode/mcp.json"
{
  "inputs": [
    {
      "type": "promptString",
      "id": "terac-api-key",
      "description": "Terac API key",
      "password": true
    }
  ],
  "servers": {
    "terac": {
      "type": "http",
      "url": "https://terac.com/api/mcp",
      "headers": {
        "x-api-key": "${input:terac-api-key}"
      }
    }
  }
}
```

Click **Start** above the server entry, or run **MCP: List Servers** from the Command Palette. For OAuth, remove the `inputs` and `headers` blocks; VS Code opens a browser to authorize on first connect.

### ChatGPT

Terac is published in the ChatGPT app directory, so there is no server URL to paste and no developer mode to enable.

1. **Open the Terac app**

   Go to [Terac in the ChatGPT app directory](https://chatgpt.com/plugins/plugin_asdk_app_699562017464819186082ec0bff33f17), or search ChatGPT's apps for **Terac**.

2. **Connect your account**

   Choose to connect and complete the sign-in when prompted. If you do not have a Terac organization yet, you can create one during this step and you will be returned to finish connecting.

3. **Pick your organization**

   Terac asks which organization the app should act on behalf of. That choice is remembered, and everything the app does afterwards is scoped to it.

Terac's tools are now available in chat. Try asking: *"Use Terac to get my organization context."*

> Prefer to wire up the raw MCP server instead, or on a plan without app
> support? Use the **Other (mcp-remote)** tab, or add
> `https://terac.com/api/mcp` as a custom connector under **Settings → Apps &
> Connectors**. Both reach the same server; the app is simply fewer steps.

### Other (mcp-remote)

Any client that can run a stdio command reaches Terac through [`mcp-remote`](https://www.npmjs.com/package/mcp-remote), which bridges a local command to the remote HTTP server and handles OAuth:

```json title="mcp config"
{
  "mcpServers": {
    "terac": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://terac.com/api/mcp"]
    }
  }
}
```

That uses browser-based OAuth. To pass an API key instead, append a header argument:

```json title="With an API key"
{
  "mcpServers": {
    "terac": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://terac.com/api/mcp",
        "--header",
        "x-api-key:tk_your_api_key"
      ]
    }
  }
}
```

If your client supports native HTTP transport, skip `mcp-remote` and point it directly at `https://terac.com/api/mcp` with an `x-api-key` header.

## Verify the Connection [#verify-the-connection]

Confirm the tools are live before relying on them.

1. **Check the server connected**

   In Claude Code, run `claude mcp list` (or `/mcp` in a session). In Cursor, VS Code, Claude, or ChatGPT, open the MCP or connector settings and look for **terac** with a connected status and a non-zero tool count.

2. **Run the first tool**

   Ask your assistant: *"Use Terac to get my organization context."* It should call `terac_get_context` and return your organization name, credit balance, and projects. If it does, you are connected.

## Troubleshooting [#troubleshooting]

### 401 Unauthorized or 'Authentication required'

Your API key is missing, malformed, or revoked. Confirm the header name is exactly `x-api-key`, the value starts with `tk_`, and the key is still active under **Settings → API Keys**. If you used an environment variable, make sure it is set in the shell or app that launched the client.

### Server shows 'failed' or no tools

Check that the URL is `https://terac.com/api/mcp` (note the `/api/mcp` path) and the transport is HTTP, not stdio, unless you are using `mcp-remote`. Restart the client after editing a config file. In Claude Code, `claude mcp get terac` prints the resolved configuration.

### OAuth browser window does not open

Some clients print a URL instead of opening a browser; copy it manually. Make sure pop-ups are allowed. If sign-in succeeds but tools still fail, the session may be bound to a different organization. Remove and re-add the server, then re-authenticate.

### 429 Rate limited

The MCP shares the API rate limit of 100 requests per minute per key. Space out high-volume operations and retry with exponential backoff. Contact support for an increase.

## What's Next? [#whats-next]

- [Terac MCP Overview](https://terac.com/docs/researchers/mcp): See the full tool catalog and launch workflow
- [API Keys](https://terac.com/docs/researchers/integrations/api-keys): Rotate, scope, and secure your keys
- [Create an Opportunity](https://terac.com/docs/researchers/opportunities/creating-an-opportunity): Understand what your agent is launching