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

# Connect VS Code

> Add the Opus MCP server to VS Code with GitHub Copilot, and keep your Opus API key out of your configuration file.

## Prerequisites

* [VS Code](https://code.visualstudio.com) with GitHub Copilot installed
* An Opus API key (see [Authentication](https://developer.opus.com/mcp/overview.md#authentication))
* Your organization enabled for the Opus MCP server (see [Overview](https://developer.opus.com/mcp/overview.md))
* The MCP URL for your Opus deployment. The examples use `https://mcp.opus.com`. For other deployments, ask the Opus team (see [Server URLs](https://developer.opus.com/mcp/overview.md#server-urls))

## Add the Server

VS Code reads MCP servers from two kinds of configuration. Use option 1 for new setups. Option 2 uses the older editor format, which VS Code will remove in February 2027.

### Option 1: Copilot configuration (recommended)

Set your key in the `OPUS_API_KEY` environment variable of the shell or session that starts VS Code. Then add the server to `~/.copilot/mcp-config.json` for every workspace, or to `.mcp.json` in the workspace root for one project:

```json ~/.copilot/mcp-config.json theme={null}
{
  "mcpServers": {
    "opus-build": {
      "type": "http",
      "url": "https://mcp.opus.com/v1/mcp/build",
      "headers": {
        "x-service-key": "${OPUS_API_KEY}"
      }
    }
  }
}
```

| Field | Purpose |
| - | - |
| `mcpServers` | One entry for each Opus server. The key (`opus-build`) is the server name. |
| `type` | `"http"` selects the Streamable HTTP transport. |
| `headers` | Sends your key as the `x-service-key` header. |
| `${OPUS_API_KEY}` | VS Code reads the key from your environment, so the key never appears in the file. |

To add the other [categories](https://developer.opus.com/mcp/overview.md#server-urls), add `opus-discover` and `opus-admin` entries under `mcpServers` with the matching URLs and the same `headers` block.

> [!NOTE]
>
> This format does not support input prompts. If you set `OPUS_API_KEY` after VS Code started, restart VS Code. See the [VS Code MCP configuration reference](https://code.visualstudio.com/docs/agents/reference/mcp-configuration).

### Option 2: Editor configuration (deprecated)

> [!WARNING]
>
> VS Code deprecated this format and will remove it in February 2027. Use option 1 for new setups.

Add the server to `.vscode/mcp.json` in your workspace. For a server in every workspace, run **MCP: Open User Configuration** from the Command Palette and add it there. This format can ask for your key in a secure prompt:

```json .vscode/mcp.json theme={null}
{
  "inputs": [
    {
      "type": "promptString",
      "id": "opus-api-key",
      "description": "Opus API key",
      "password": true
    }
  ],
  "servers": {
    "opus-build": {
      "type": "http",
      "url": "https://mcp.opus.com/v1/mcp/build",
      "headers": {
        "x-service-key": "${input:opus-api-key}"
      }
    }
  }
}
```

VS Code asks for the key the first time the server starts and stores it securely, so the key never appears in the file. You can commit this file: each teammate enters their own key. To add the other categories, add `opus-discover` and `opus-admin` entries under `servers` that refer to the same `${input:opus-api-key}`.

## Verify

Ask the agent (Copilot in agent mode) to call `list_workspaces` on `opus-build`. A list of your workspaces means the connection works.

> [!WARNING]
>
> A server that starts without an error proves only that the MCP handshake worked. Always confirm with a real tool call such as `list_workspaces`.

## Troubleshooting

See [Troubleshooting](https://developer.opus.com/mcp/troubleshooting.md) for all errors.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.