# Connect an MCP Client

> Connect Claude, GitHub Copilot, Cursor, Microsoft Copilot, the OpenAI API or any MCP client to the CapaOne MCP server.

Source: https://docs.capaone.com/capaone/mcp-and-api/connect-an-mcp-client/  
Product: CapaOne — a separate CapaSystems product; do not apply this page to any other.

The CapaOne MCP server lets AI agents search your devices. Add it to your client with its URL and
your API key.

## Server details

| Setting | Value |
|---|---|
| URL | `https://mcp.capaone.com/mcp` |
| Transport | Streamable HTTP |
| Authentication | `X-Api-Key: <your API key>` |

The server is stateless and read-only, and only sees the organization your API key belongs to. Its
tools are described in [MCP Tools](/capaone/mcp-and-api/mcp-tools/).

The API key is the only way to authenticate. The server doesn't support OAuth, so a client must be
able to send the `X-Api-Key` header with every request.

:::caution[Your key, your data]
The agent sees whatever the tools return for your organization. Only connect clients and models
that your organization allows to process device and user data.
:::

## Clients at a glance

| Client | How it connects |
|---|---|
| [Claude Code](#claude-code) | `claude mcp add`, or the project's `.mcp.json` |
| [Claude](#claude) on the web, desktop and mobile | A custom connector with a request header, or the desktop app's configuration file |
| [VS Code (GitHub Copilot)](#vs-code-github-copilot) | `~/.copilot/mcp-config.json` |
| [Cursor](#cursor) | `mcp.json` |
| [Microsoft 365 Copilot and Teams](#microsoft-365-copilot-and-teams) | An agent you build in Microsoft Copilot Studio |
| [ChatGPT](#chatgpt) | Not supported. Use the OpenAI API instead. |

Any other client that supports Streamable HTTP and custom headers works too. Use the URL and header
from [Server details](#server-details).

## Keep the key in an environment variable

Several setups below read the key from the `CAPAONE_API_KEY` environment variable, so the key isn't
saved in a configuration file. Set it once for your user account, then restart the client:

```powershell title="PowerShell (Windows)"
[Environment]::SetEnvironmentVariable('CAPAONE_API_KEY', '<your API key>', 'User')
```

```sh title="macOS or Linux (~/.zshrc or ~/.bashrc)"
export CAPAONE_API_KEY="<your API key>"
```

## Client setup

### Claude Code

Run this once in your terminal:

```sh title="Terminal"
claude mcp add --transport http capaone https://mcp.capaone.com/mcp --header "X-Api-Key: <your API key>"
```

Add `--scope user` to make the server available in every project. Check the connection with `/mcp`
inside Claude Code.

To share the server with your team, add it to the project's `.mcp.json` instead. Reference the
environment variable, so the key isn't committed with the project:

```json title=".mcp.json"
{
  "mcpServers": {
    "capaone": {
      "type": "http",
      "url": "https://mcp.capaone.com/mcp",
      "headers": {
        "X-Api-Key": "${CAPAONE_API_KEY}"
      }
    }
  }
}
```

Claude Code asks each person to approve the project's servers the first time. A custom connector
you add in [Claude](#claude) also appears in Claude Code when you sign in with the same Claude
account.

### Claude

Claude on the web and in the desktop and mobile apps connects through a custom connector, with the
key in a request header.

:::note[Request headers are in beta]
Request headers are available to a limited set of Claude organizations. If the **Add custom
connector** dialog has no **Request headers** section, use the
[Claude Desktop configuration file](#claude-desktop-configuration-file) instead.
:::

On a Free, Pro, Max or Ultra plan:

1. Go to **Customize → Connectors** and select **Add custom connector**.
2. Enter a name, such as `CapaOne`, and the server URL `https://mcp.capaone.com/mcp`.
3. If you're asked for **Authentication**, choose **No sign-in**.
4. Open **Request headers** and select `x-api-key` as the header name.
5. Enter your API key as the value, and mark the header **Required**.
6. Select **Add**.

CapaOne appears under **Customize → Connectors**. In a chat, turn it on or off under
**+ → Connectors**.

On a Team or Enterprise plan, an Owner adds the connector for the whole organization. In
**Organization settings → Connectors**, select **Add**, then **Custom**, choose **Web** if asked,
and use the same settings. Members then select **Connect** next to CapaOne under
**Customize → Connectors**. Everyone in the organization reads CapaOne with that one key.

You can't change a request header after you add the connector. To use a new key, remove the
connector and add it again.

#### Claude Desktop configuration file

Without request headers, Claude Desktop connects through the
[mcp-remote](https://www.npmjs.com/package/mcp-remote) bridge, which needs Node.js. Open
**Settings → Developer → Edit Config** and add:

```json title="claude_desktop_config.json"
{
  "mcpServers": {
    "capaone": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.capaone.com/mcp",
        "--header",
        "X-Api-Key:${CAPAONE_API_KEY}"
      ],
      "env": {
        "CAPAONE_API_KEY": "<your API key>"
      }
    }
  }
}
```

Keep `X-Api-Key:${CAPAONE_API_KEY}` without a space after the colon. On Windows, Claude Desktop
splits arguments that contain spaces. Restart Claude Desktop afterwards.

### VS Code (GitHub Copilot)

Add the server to your Copilot configuration file, `~/.copilot/mcp-config.json`
(`%USERPROFILE%\.copilot\mcp-config.json` on Windows). The header reads the key from the
[`CAPAONE_API_KEY` environment variable](#keep-the-key-in-an-environment-variable):

```json title="mcp-config.json"
{
  "mcpServers": {
    "capaone": {
      "type": "http",
      "url": "https://mcp.capaone.com/mcp",
      "headers": {
        "X-Api-Key": "${CAPAONE_API_KEY}"
      }
    }
  }
}
```

Restart VS Code afterwards. The server is then available in every workspace.

If you added CapaOne to `.vscode/mcp.json` with a prompt for the key, move it to the file above.
VS Code's default Copilot harness doesn't load servers that prompt for input, so the CapaOne tools
are missing from its sessions.

:::note[Copilot Business and Copilot Enterprise]
MCP servers only work after an administrator turns on the **MCP servers in Copilot** policy for
your enterprise or organization. The policy is off by default.
:::

### Cursor

Add the server to `~/.cursor/mcp.json`, or `.cursor/mcp.json` in a project, and set the
[`CAPAONE_API_KEY` environment variable](#keep-the-key-in-an-environment-variable):

```json title="mcp.json"
{
  "mcpServers": {
    "capaone": {
      "url": "https://mcp.capaone.com/mcp",
      "headers": {
        "X-Api-Key": "${env:CAPAONE_API_KEY}"
      }
    }
  }
}
```

### Microsoft 365 Copilot and Teams

Microsoft 365 Copilot can't add the CapaOne MCP server by itself. Its own ways of adding an MCP
server accept only OAuth, Microsoft Entra SSO or no authentication. Instead, build an agent in
Microsoft Copilot Studio, which can send the API key, and publish it to Microsoft 365 Copilot and
Teams. [Connect Microsoft Copilot](/capaone/mcp-and-api/connect-microsoft-copilot/) has the steps.

The Microsoft Copilot app for consumers has no option to add an MCP server.

### ChatGPT

ChatGPT can't connect to the CapaOne MCP server. ChatGPT only adds MCP servers that use OAuth or no
authentication, and it can't send an API key.

To use the CapaOne tools with OpenAI models, call them through the OpenAI API instead. In the
Responses API, add the server to the request's `tools`, with the key in `headers`:

```json title="Responses API tool"
{
  "type": "mcp",
  "server_label": "capaone",
  "server_url": "https://mcp.capaone.com/mcp",
  "headers": {
    "X-Api-Key": "<your API key>"
  },
  "require_approval": "never"
}
```

- Send the header with every request. OpenAI doesn't keep it between requests.
- Every CapaOne tool is read-only, so `require_approval` can be `never`. Without it, the API asks
  your code to approve each tool call.

The OpenAI Agents SDK takes the same header in its MCP server settings.

## Test the connection

The [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) lists the server's tools
from the command line. It needs Node.js 22.19 or newer:

```sh title="Terminal"
npx @modelcontextprotocol/inspector --cli https://mcp.capaone.com/mcp --transport http --header "X-Api-Key: <your API key>" --method tools/list
```

The command prints the CapaOne tools as JSON. If the key is missing, expired or revoked, the server
answers `401`.

To call the tools by hand, open the Inspector in your browser instead:

```sh title="Terminal"
npx @modelcontextprotocol/inspector --server-url https://mcp.capaone.com/mcp --transport http --header "X-Api-Key: <your API key>"
```

Connect to the server, open **Tools**, and call `list_filterable_fields`. The tool returns the
device fields and operators that search accepts.

## Example prompts

Once connected, ask about your devices in plain language:

- Which organization are you connected to?
- Which devices are offline right now?
- List the Windows 10 devices that have not checked in for 30 days.
- How many devices have failed software patches? Show the worst ten.
- Find the laptop used by Jane Doe and tell me its OS version.
- Which devices have less than 8 GB of RAM?
- What is installed on LAPTOP-0042, and who are its local administrators?

To turn the answers into charts and tiles, see
[Build a Dashboard with Claude](/capaone/mcp-and-api/build-a-dashboard-with-claude/).

Each tool call is one API request and counts towards your rate limit. See
[Rate Limits and Errors](/capaone/mcp-and-api/rate-limits-and-errors/).