> ## 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 Claude Desktop

> Add the Opus MCP server to Claude Desktop with a custom connector or a local configuration file.

## Prerequisites

* [Claude Desktop](https://claude.ai/download) 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))

## Choose a Method

Claude Desktop can reach the Opus MCP server in two ways. Both send your Opus API key as the `x-service-key` header.

| Method | Best for | Where it runs |
| - | - | - |
| [Custom connector](#option-1-custom-connector) | Pro and Max plans, one person per Claude account | Anthropic's cloud connects to Opus |
| [Local config with `mcp-remote`](#option-2-local-config-with-mcp-remote) | Team and Enterprise plans, or when you cannot add a custom connector | A small bridge on your computer connects to Opus |

## Option 1: Custom Connector

Custom connectors can send fixed request headers, such as an API key, on every request.

**1. Open the connector settings**

In Claude, go to **Customize > Connectors**, click **+ Add**, then click **Add custom connector**.

**2. Enter the name and URL**

* **Name**: `opus-build`
* **Remote MCP server URL**: `https://mcp.opus.com/v1/mcp/build`

Click **Continue**.

**3. Set authentication**

Under **Authentication**, choose **No sign in**.

**4. Add your API key as a request header**

Under **Request headers**, add:

* **Header**: `x-service-key`
* **Value**: your Opus API key

Click **Add**.

**5. Repeat for other categories**

Add a separate connector for each [category](https://developer.opus.com/mcp/overview.md#server-urls) you need, for example `opus-discover` with `https://mcp.opus.com/v1/mcp/discover`.

> [!WARNING]
>
> On Team and Enterprise plans, an Owner adds custom connectors for the whole organization, and **every member uses the same request header**. Opus API keys belong to one user, so every member would act in Opus as the person who created the key. On those plans, use [Option 2](#option-2-local-config-with-mcp-remote) so each person uses their own key.

> [!NOTE]
>
> Free plans allow only one custom connector, so you can connect only one Opus category this way.

## Option 2: Local Config with `mcp-remote`

The [`mcp-remote`](https://github.com/geelen/mcp-remote) package runs on your computer and forwards requests to the Opus MCP server with your API key. It needs [Node.js](https://nodejs.org) 18 or later, so that `npx` is available.

**1. Open the configuration file**

In Claude Desktop, open **Settings > Developer** and click **Edit Config**. This opens `claude_desktop_config.json`:

* **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
* **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

**2. Add the Opus servers**

Add one entry for each category you need:

```json claude_desktop_config.json theme={null}
{
  "mcpServers": {
    "opus-build": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.opus.com/v1/mcp/build",
        "--transport",
        "http-only",
        "--header",
        "x-service-key:${OPUS_API_KEY}"
      ],
      "env": {
        "OPUS_API_KEY": "<your_api_key>"
      }
    },
    "opus-discover": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.opus.com/v1/mcp/discover",
        "--transport",
        "http-only",
        "--header",
        "x-service-key:${OPUS_API_KEY}"
      ],
      "env": {
        "OPUS_API_KEY": "<your_api_key>"
      }
    }
  }
}
```

Replace `<your_api_key>` with your Opus API key. `mcp-remote` replaces `${OPUS_API_KEY}` with the value from `env`.

The `env` block holds your key in plain text in `claude_desktop_config.json`. Do not share or commit this file. As an alternative, `mcp-remote` can read headers from a separate file with `--header-file <path>`, one `Name: value` per line. See the [`mcp-remote` README](https://github.com/geelen/mcp-remote).

**3. Restart Claude Desktop**

Quit Claude Desktop completely and open it again. It loads the configuration only at startup.

> [!WARNING]
>
> Keep **no spaces** in the header argument: write `x-service-key:${OPUS_API_KEY}`, not `x-service-key: ${OPUS_API_KEY}`. Claude Desktop on Windows does not escape spaces inside `args` when it starts `npx`, which breaks the header. The format without spaces works on every platform.

> [!NOTE]
>
> `--transport http-only` makes `mcp-remote` use Streamable HTTP only. The Opus MCP server does not support the older SSE transport.

## Verify

In a new chat, ask the agent to call `list_workspaces` on `opus-build`. A list of your workspaces means the connection works.

## Troubleshooting

If a local `mcp-remote` server does not connect, check the MCP logs:

* **macOS**: `~/Library/Logs/Claude/mcp*.log`
* **Windows**: `%APPDATA%\Claude\logs\mcp*.log`

A `401`, or an OAuth or client registration error, in the log means the server rejected the key or your organization. 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.