> For the complete documentation index, see [llms.txt](https://docs.groundcover.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.groundcover.com/getting-started/groundcover-mcp/configure-groundcovers-mcp-server.md).

# Configure groundcover's MCP Server

Set up your agent to talk to groundcover's MCP server. Use OAuth for a quick login, or an API key for service accounts.

The MCP endpoint is:

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

{% hint style="info" %}
Self-hosted (on-prem / air-gapped) deployments use their own MCP URL. Replace `https://mcp.groundcover.com/api/mcp` with your environment's endpoint everywhere in this guide.
{% endhint %}

**The MCP server supports two methods:**

* [**OAuth**](#oauth-recommended) (Recommended for IDEs)
* [**API Key**](#api-key)

## OAuth (recommended)

**OAuth is the default** if your agent supports it.

Add the config below to your MCP client. The first time it connects, your browser opens and prompts you to log in with your groundcover credentials. If you have access to more than one workspace, your agent picks the target workspace using the `list_workspaces` tool — or you can [pin a specific one](#optional-headers).

{% hint style="info" %}
**Pro tip**: You can copy a ready-to-go config from the UI.\
Go to the sidebar → Click your profile picture → **"Connect to our MCP"**
{% endhint %}

<figure><img src="/files/OfgJpBR7zEDKp6VgZTNX" alt="" width="563"><figcaption></figcaption></figure>

**Cursor / generic `mcp.json`**

```json
{
  "mcpServers": {
    "groundcover": {
      "type": "http",
      "url": "https://mcp.groundcover.com/api/mcp"
    }
  }
}
```

To roll the server out to your whole Cursor organization at once, see [Cursor Team MCP](#cursor-team-mcp-cloud-agents).

**Claude Code**

```bash
claude mcp add --transport http groundcover https://mcp.groundcover.com/api/mcp
```

Then run `/mcp` inside Claude Code to complete the browser login.

**Codex**

```bash
codex mcp add groundcover --url https://mcp.groundcover.com/api/mcp
codex mcp login groundcover
```

**Other clients (e.g. Claude Web)**

Point the client at the remote endpoint:

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

## API Key

If your agent doesn't support OAuth, or if you want to connect a service account, use an API key. The client authenticates with a `Bearer` token — the key is already scoped to a tenant, and its backend is selected automatically, so the token is all you need.

### Prerequisites

1. **Service‑account API key** – create one or use an existing API Key. Learn more at [groundcover API keys](https://docs.groundcover.com/use-groundcover/api-keys).

### Configuration Example

```json
{
  "mcpServers": {
    "groundcover": {
      "type": "http",
      "url": "https://mcp.groundcover.com/api/mcp",
      "headers": {
        "Authorization": "Bearer <your_token>"
      }
    }
  }
}
```

For **Claude Code**:

```bash
claude mcp add --transport http groundcover https://mcp.groundcover.com/api/mcp \
  --header "Authorization: Bearer <your_token>"
```

To target a specific backend (when the tenant has more than one) or set your time zone, add an [optional header](#optional-headers).

## Optional Headers

A connection is always scoped to one workspace (tenant + backend), and it's resolved automatically: with **OAuth** your agent selects the workspace via `list_workspaces` (or uses your only one); with an **API key** the tenant comes from the key and a single backend is auto-selected.

To override that, add any of these headers to your config's `headers` block (or as `--header` flags). They work with both OAuth and API-key connections:

| Header          | When to use                                                                                                                               |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `X-Tenant-UUID` | Pin an OAuth connection to a single workspace (you must be a member). Not needed with an API key — its tenant is fixed by the key.        |
| `X-Backend-Id`  | Choose the backend when the tenant has more than one.                                                                                     |
| `X-Timezone`    | Your [IANA time zone](#how-to-find-your-time-zone) (for example `America/New_York`), so relative time windows resolve to your local time. |

For example, to pin an OAuth client to a single workspace:

```json
{
  "mcpServers": {
    "groundcover": {
      "type": "http",
      "url": "https://mcp.groundcover.com/api/mcp",
      "headers": {
        "X-Tenant-UUID": "<your_tenant_uuid>"
      }
    }
  }
}
```

**Where to find your tenant UUID and backend ID**

* Go to the sidebar → Click your **profile picture** → **"Connect to our MCP"**.
* Alternatively: **Settings → Access → API Keys** tab.

## **How to find your time zone**

| OS                 | Command                           |
| ------------------ | --------------------------------- |
| macOS              | `sudo systemsetup -gettimezone`   |
| Linux              | `timedatectl \| grep "Time zone"` |
| Windows PowerShell | `Get-TimeZone`                    |

## Cursor Team MCP (Cloud Agents)

**Team MCP** lets a Cursor admin configure groundcover's MCP server once for the entire organization, instead of every engineer editing their own `mcp.json`. Each user then logs in once with OAuth and the server becomes available to their agents.

{% hint style="warning" %}
Team MCP is a **Cursor Cloud Agents** feature, and it must be configured from the **web UI**. The Cursor IDE's **Settings → MCP Servers** screen only offers the command (stdio) option and will not work here.
{% endhint %}

### Add the server (admin, once)

1. Open Cursor Cloud Agents in the browser. From the IDE you can get there via **Configure Team MCP Servers** — this opens the web UI on a settings screen, so press the browser's **back** button to land on the agent window with the chat input.
2. In the chat input, click the **`+`** button → **MCP Servers** → **Add MCP**.

<figure><img src="/files/J15xKfBklRD1X6rJYw1k" alt="Cursor chat input with the plus menu open on MCP Servers, showing the Add MCP option"><figcaption></figcaption></figure>

3. In the **Browse MCPs** dialog, choose **Custom MCP**.

<figure><img src="/files/igaQU7jiT9lMh1UzYx95" alt="Cursor Browse MCPs dialog showing the Custom MCP option"><figcaption></figcaption></figure>

4. Fill in the **Add a Custom MCP** dialog:

| Field          | Value                                 |
| -------------- | ------------------------------------- |
| **Access**     | **Team** — see the note below         |
| **Name**       | `groundcover`                         |
| **Type**       | **URL**                               |
| **Server URL** | `https://mcp.groundcover.com/api/mcp` |
| **Headers**    | Leave empty — no API key needed       |

<figure><img src="/files/c2NU9RGmv5JWsX4U6wgT" alt="Cursor Add a Custom MCP dialog filled in with Access set to Team and the groundcover MCP URL"><figcaption></figcaption></figure>

5. Click **Add MCP**.

{% hint style="danger" %}
Make sure **Access** is set to **Team**. If it's left on the personal option, only the user who created the server will see it.
{% endhint %}

groundcover's MCP server fully supports OAuth over remote HTTPS — leave **Headers** empty and don't fall back to a `Command` / `npx mcp-remote` configuration.

### Make it available in the IDE and CLI

By default a Team MCP server is only available to **cloud agents**. To also expose it locally in the Agent Window, IDE, and CLI, go to **Settings → Team MCP Servers** and click **Add to Team Marketplace**.

<figure><img src="/files/8JeADmz60GRUhA46SY8L" alt="Cursor Team MCP Servers settings showing the Add to Team Marketplace button"><figcaption></figcaption></figure>

### Log in (each user)

Once the server is shared, every user clicks **`+`** → **MCP Servers** and sees a **Login** button next to **groundcover**. After a single browser login with their groundcover credentials, the MCP server is available to their Cursor agents.

### Troubleshooting

| Issue                                                        | Resolution                                                                                                                                                     |
| ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| "Add a custom MCP" only shows the **Command** option         | You're in the Cursor IDE. Team MCP must be configured from the Cursor Cloud Agents web UI — see the steps above.                                               |
| The **Access** field isn't shown                             | Same cause: the field only appears in the web UI. If you want the server usable from the IDE, add it in the web UI and then click **Add to Team Marketplace**. |
| Other users don't see the server                             | **Access** wasn't set to **Team**, or the server wasn't added to the Team Marketplace.                                                                         |
| Error when adding the server from **Settings → MCP Servers** | That path doesn't support the Team MCP remote HTTPS flow. Use the **`+` → MCP Servers → Add MCP** path in the web UI.                                          |

## **Client‑specific Guides**

Depending on your client, you can usually set up the MCP server through the UI - or just ask the client to add it for you. Here are quick links for common tools:

* [Instructions for Claude Desktop](https://modelcontextprotocol.io/quickstart/user#2-add-the-filesystem-mcp-server)
* [Instructions for Claude Web](https://support.anthropic.com/en/articles/11175166-about-custom-integrations-using-remote-mcp)
* [Instructions for Cursor](https://docs.cursor.com/context/model-context-protocol#configuring-mcp-servers)
* [Instructions for Windsurf](https://docs.windsurf.com/windsurf/mcp)
* [Instructions for VS Code](https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_add-an-mcp-server-to-your-workspace)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.groundcover.com/getting-started/groundcover-mcp/configure-groundcovers-mcp-server.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.