---
title: Connect your AI client
description: >-
  Connect Claude, Cursor, Claude Code, or GitHub Copilot to Kapptivate's MCP
  server using an API key or browser-based OAuth sign-in.
sidebarTitle: AI clients
lastUpdated: "2026-09-23"
---

> **For AI agents:** the complete documentation index is at [llms.txt](/llms.txt). Append `.md` to any page URL for its markdown version.

Point any MCP-compatible client at your endpoint and authenticate either with a browser sign-in (OAuth) or with the `X-Kapptivate-API-Key` header. This page covers the common developer clients (Claude Code, Cursor, Claude Desktop, and GitHub Copilot). For Microsoft 365 Copilot Studio and Google Gemini, see their dedicated pages in this section.

## Your endpoint

Sign in to Kapptivate at app.kapptivate.com, and this is your endpoint:

```
https://mcp.kapptivate.com/mcp
```

Sign in somewhere else and your endpoint carries the name of your environment. Take the first part of the address you sign in with, and put it after `/t/`:

```
https://mcp.kapptivate.com/t/<environment>/mcp
```

An account on `acme.kapptivate.com` connects to `https://mcp.kapptivate.com/t/acme/mcp`. Every example below carries the app.kapptivate.com address, so substitute yours before you copy one.

## Get your API key

<Steps>
  <Step title="Open your profile">
    Sign in to Kapptivate at the address you use, the same one that gave you your endpoint above, and open your profile.
  </Step>
  <Step title="Copy your API key">
    Copy your personal API key. It carries the same access as your account. Workspace-level keys, scoped to teams, are managed under [Administration > API keys](/administration/api-keys).
  </Step>
</Steps>

<Warning>
  Treat the key like a password. Prefer an environment variable over pasting it into a config file you might commit.
</Warning>

<Note>
  Prefer signing in with your browser? Clients that implement MCP authorization (Claude custom connectors, for example) can skip the API key entirely: add the server URL without any header and the client walks you through a browser sign-in (OAuth). This works with clients that carry MCP authorization natively, such as Claude custom connectors. It does not work through `mcp-remote`: that proxy requires dynamic client registration, which this authorization server does not offer, so it exits at startup with `Incompatible auth server`. Keep the API key for the Claude Desktop setup below.
</Note>

## Access scopes

A browser sign-in grants three scopes. An API key carries the full rights of your account.

| Scope | What it allows |
| --- | --- |
| `read` | Browse every Kapptivate resource: tests, monitors, dashboards, metrics, robots |
| `write` | Create, edit and run those resources |
| `admin` | Privileged actions: shell commands on robots, restart and maintenance, incident closure |

`admin` lets an assistant restart your robots, so read the consent screen before you approve it. To see what a client holds today, or to take it back, open `https://<your-environment>/o/authorized_tokens/`. Revoking there cuts off that client immediately and changes nothing else.

## Configure your client

<Tabs>
<Tab title="Claude Code">

Register the server with one command, then confirm it connected:

```bash
claude mcp add --transport http kapptivate https://mcp.kapptivate.com/mcp \
  --header "X-Kapptivate-API-Key: $KAPPTIVATE_API_KEY"

claude mcp list
```

</Tab>
<Tab title="Cursor">

Add Kapptivate to your MCP configuration (Settings, then MCP):

```json
{
  "mcpServers": {
    "kapptivate": {
      "url": "https://mcp.kapptivate.com/mcp",
      "headers": {
        "X-Kapptivate-API-Key": "YOUR_KEY"
      }
    }
  }
}
```

</Tab>
<Tab title="Claude Desktop">

Claude Desktop reaches remote servers through `mcp-remote`. Edit `claude_desktop_config.json`, then restart Claude Desktop:

```json
{
  "mcpServers": {
    "kapptivate": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://mcp.kapptivate.com/mcp",
        "--header", "X-Kapptivate-API-Key:YOUR_KEY"
      ]
    }
  }
}
```

</Tab>
<Tab title="GitHub Copilot">

In VS Code, add a `.vscode/mcp.json` to your workspace (or run **MCP: Open User Configuration** to apply it everywhere):

```json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "kapptivate-key",
      "description": "Kapptivate API key",
      "password": true
    }
  ],
  "servers": {
    "kapptivate": {
      "type": "http",
      "url": "https://mcp.kapptivate.com/mcp",
      "headers": {
        "X-Kapptivate-API-Key": "${input:kapptivate-key}"
      }
    }
  }
}
```

Open Copilot Chat in agent mode, then start the server from **MCP: List Servers** in the Command Palette. VS Code prompts for the key on first use and stores it securely.

<Note>
  This is GitHub Copilot in your editor. It is a different product from [Microsoft Copilot Studio](/mcp/integrations/copilot-studio) (the Microsoft 365 agent builder).
</Note>

</Tab>
</Tabs>

## Verify the connection

Ask your assistant for something read-only, for example: "List the operators I can access." If it returns results, you are connected.

## Common errors

Connecting only proves the address exists. Your environment is resolved later, when a tool runs, so a client can report the server as connected and still fail on its first call. In its error messages, the server calls an environment a tenant.

<Warning>
  A green connection status is not proof that your endpoint is right. Run [the read-only check above](#verify-the-connection).
</Warning>

| What you see | What it means | What to do |
| --- | --- | --- |
| 401 | No credentials, or credentials issued for another environment | Send your API key in the `X-Kapptivate-API-Key` header, or sign in through the browser, which carries an `Authorization: Bearer` session instead. Check that the key belongs to the environment in the URL. |
| 404 | The path is missing its `/t/` segment | Write `https://mcp.kapptivate.com/t/<environment>/mcp`, never `https://mcp.kapptivate.com/<environment>/mcp`. |
| 400, `invalid tenant path` | The path carries a full address | Keep only the first part of your sign-in address, without `.kapptivate.com`. |
| Connects, then every tool call fails | The key and the path name two different environments | Line them up, then reconnect the client. |

Still stuck? Write to support@kapptivate.com with the endpoint you used and the code you got back.

## What's next?

<Columns cols={2}>
  <Card title="Microsoft Copilot Studio" icon="robot" href="/mcp/integrations/copilot-studio">
    Connect from Microsoft 365.
  </Card>
  <Card title="Google Gemini" icon="sparkles" href="/mcp/integrations/gemini">
    Connect Gemini, from CLI to enterprise.
  </Card>
  <Card title="Example prompts" icon="robot" href="/mcp/examples">
    What to ask once you are connected.
  </Card>
  <Card title="Core concepts" icon="sitemap" href="/mcp/concepts">
    Operators, products, variables, and the safety model.
  </Card>
</Columns>