> 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"
    }
  }
}
```

**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`                    |

## **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.