> ## Documentation Index
> Fetch the complete documentation index at: https://docs.operata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect GitHub Copilot

> Configure GitHub Copilot in VS Code, Visual Studio, JetBrains, or the Copilot CLI to query your Operata traces over the Model Context Protocol.

GitHub Copilot can call the Operata MCP Server from agent mode, so you can ask about call quality, traces, and agent experience without leaving your editor.

This page covers the Copilot surfaces that connect to a remote MCP server directly. If you want to build an agent for non-technical colleagues instead, see [Connect Microsoft Copilot Studio](/docs/guides-mcp-copilot-studio).

For authentication, groups, and regions, start with the [Operata MCP server](/docs/guides-mcp-intro) overview.

<Info>
  MCP tools only appear in **agent mode**. They're invisible in Ask and Edit modes.
</Info>

## Before you start

* An active Operata subscription and credentials for your chosen endpoint — see [Choose how to connect](/docs/guides-mcp-intro#choose-how-to-connect).
* A GitHub Copilot subscription.
* One of: VS Code 1.101 or later, Visual Studio 2022 17.14 or later, a JetBrains IDE with the Copilot plugin, or GitHub Copilot CLI.
* If your organization is on Copilot Business or Copilot Enterprise, an administrator must enable the **MCP servers in Copilot** policy. Without it, the server won't load and Copilot gives no error.

## Configuration file locations

| Client              | File                                                   |
| :------------------ | :----------------------------------------------------- |
| VS Code (workspace) | `.vscode/mcp.json`                                     |
| VS Code (user)      | Command Palette → **MCP: Open User Configuration**     |
| Visual Studio       | `mcp.json`, created by the Configure MCP server dialog |
| JetBrains IDEs      | `mcp.json`, created by **Add MCP Tools**               |
| Copilot CLI         | `~/.copilot/mcp-config.json`                           |

<Warning>
  In VS Code, Visual Studio, and JetBrains, the configuration root key is `servers`, not `mcpServers`. Cursor and Claude Desktop use `mcpServers`, so a config copied from one of those pages silently fails to load. This is the most common setup mistake. The Copilot CLI is the exception — it uses `mcpServers` (see [GitHub Copilot CLI](#github-copilot-cli)).
</Warning>

## Connect with OAuth

Recommended when a person is at the keyboard. OAuth signs you in as your Operata user and reaches every group your account can access.

Add the server to your configuration file:

```json .vscode/mcp.json theme={null}
{
  "servers": {
    "operata": {
      "type": "http",
      "url": "https://mcp.operata.io/mcp"
    }
  }
}
```

In VS Code, a **Start** button appears above the server entry. Select it. Copilot opens an Operata sign-in in your browser and stores the session for later. If the server is already running, use the **Auth** action in the CodeLens above the entry to re-authenticate.

## Connect with an API key

Use an API key only for automated, non-interactive work. The key is fixed to the single group it was created in.

Reference the key through an input variable so it's never written into the file:

```json .vscode/mcp.json theme={null}
{
  "servers": {
    "operata": {
      "type": "http",
      "url": "https://api.operata.io/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${input:operata-api-key}"
      }
    }
  },
  "inputs": [
    {
      "id": "operata-api-key",
      "type": "promptString",
      "description": "Operata API key",
      "password": true
    }
  ]
}
```

Copilot prompts for the key the first time the server starts and keeps it for later sessions.

<Warning>
  Never commit an API key to `.vscode/mcp.json`. If the file is in a shared repository, use the user-level configuration or an input variable as shown above.
</Warning>

## Client-specific setup

### VS Code

1. Open the Command Palette and run **MCP: Open User Configuration**, or create `.vscode/mcp.json` in your workspace root.
2. Add one of the configurations above.
3. Select **Start** above the server entry.
4. Open Copilot Chat and select **Agent** from the mode dropdown.
5. Select the tools icon to confirm the Operata tools are listed.

### Visual Studio

1. From the menu bar, select **View → GitHub Copilot Chat**.
2. At the bottom of the chat panel, select **Agent** from the mode dropdown.
3. Select the tools icon, then the plus icon.
4. In **Configure MCP server**, set **Server ID** to `operata`, **Type** to `HTTP/SSE`, and **URL** to `https://mcp.operata.io/mcp`.
5. Select **Save**.

### JetBrains IDEs

1. In the lower right corner, open the Copilot menu and select **Open Chat**.
2. Switch to **Agent** mode.
3. Select the tools icon, then **Add MCP Tools**.
4. Add one of the configurations above to `mcp.json`.

### GitHub Copilot CLI

The CLI uses the **`mcpServers`** root key, not `servers` like the IDEs. Add the Operata server to `~/.copilot/mcp-config.json` with `"type": "http"`:

```json ~/.copilot/mcp-config.json theme={null}
{
  "mcpServers": {
    "operata": {
      "type": "http",
      "url": "https://mcp.operata.io/mcp"
    }
  }
}
```

For an API key, use the API endpoint and add an `Authorization` header:

```json ~/.copilot/mcp-config.json theme={null}
{
  "mcpServers": {
    "operata": {
      "type": "http",
      "url": "https://api.operata.io/v1/mcp",
      "headers": {
        "Authorization": "Bearer <your-operata-api-key>"
      }
    }
  }
}
```

The CLI supports both local and remote servers.

## Verify the connection

Open Copilot Chat in agent mode and ask:

```
List my Operata groups.
```

Copilot asks permission before calling a tool. Allow it. You should see the groups your account can reach, each with its ID and region.

Then set a group and try a real question:

```
Switch to the group named Demonstrata, then show me the average MOS score by queue for the last 7 days.
```

## Select a group

Every query runs against one group. Over OAuth, call `list_groups` then `switch_group`, and override on a single call with a `groupId` parameter. An API key is fixed to its own group. See [Groups and regions](/docs/guides-mcp-intro#groups-and-regions). For more example prompts, see [Questions to ask your AI client](/docs/guides-mcp-intro#questions-to-ask-your-ai-client).

## Troubleshooting

| Symptom                                              | Cause and fix                                                                                                               |
| :--------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------- |
| No Operata tools in the tool picker                  | You're in Ask or Edit mode. Switch to Agent.                                                                                |
| Server does not appear at all                        | Wrong root key. VS Code, Visual Studio, and JetBrains use `servers`; the Copilot CLI uses `mcpServers`.                     |
| `MCP server "operata" has a "url" but no "type"`     | Add `"type": "http"` to the entry. Without it, the client reads the entry as a local stdio server.                          |
| Server loads but every call fails with 401           | The API key is missing, expired, or the `Authorization` header is malformed. Confirm the value starts with `Bearer `.       |
| `403 API key access is restricted to its own group`  | The session is authenticated with an API key and something tried to switch groups. Use OAuth, or query the key's own group. |
| Nothing loads, no error, organization-managed device | The **MCP servers in Copilot** policy is disabled. Ask your GitHub administrator to enable it.                              |
| Repeated timeouts on large queries                   | Narrow the time range, and paginate `traces_list` with the cursor. See [Performance](/docs/guides-mcp-intro#performance).   |

For more, see [Troubleshoot the MCP server](/docs/guides-mcp-troubleshooting).

## Related

* [Operata MCP server](/docs/guides-mcp-intro) — authentication, groups, and regions.
* [Connect Microsoft Copilot Studio](/docs/guides-mcp-copilot-studio) — build an agent for non-technical users.
* [MCP tools reference](/docs/guides-mcp-tools) — every tool, its parameters, and examples.
* [Troubleshoot the MCP server](/docs/guides-mcp-troubleshooting) — common failure modes and fixes.
* [Authentication](/docs/api-authentication) — mint the API keys the server uses.
* [Rate limits](/docs/api-rate-limits) — the 100 requests per minute per key limit.