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

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.

The MCP server supports two methods:

OAuth (Recommended for IDEs)
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.

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"

Cursor / generic mcp.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.

Claude Code

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

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

Codex

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

Service‑account API key – create one or use an existing API Key. Learn more at groundcover API keys.

Configuration Example

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

For Claude Code:

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

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 (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:

{
  "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

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.

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.

Add the server (admin, once)

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.
In the chat input, click the + button → MCP Servers → Add MCP.

Cursor chat input with the plus menu open on MCP Servers, showing the Add MCP option

In the Browse MCPs dialog, choose Custom MCP.

Cursor Browse MCPs dialog showing the Custom MCP option

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

Cursor Add a Custom MCP dialog filled in with Access set to Team and the groundcover MCP URL

Click Add MCP.

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.

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.

Cursor Team MCP Servers settings showing the Add to Team Marketplace button

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:

Last updated 19 days ago