> ## 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 Code

> Add the Opus MCP server to Claude Code and keep your Opus API key in an environment variable.

## Prerequisites

* [Claude Code](https://code.claude.com/docs) 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

Add one server for each [category](https://developer.opus.com/mcp/overview.md#server-urls) you need.

**1. Store your key in an environment variable**

```bash theme={null}
export OPUS_API_KEY="<your_api_key>"
```

Add this line to your shell profile (for example `~/.zshrc`) so it is set in every terminal.

**2. Add the categories you need**

```bash Build theme={null}
claude mcp add --transport http opus-build https://mcp.opus.com/v1/mcp/build \
  --header 'x-service-key: ${OPUS_API_KEY}'
```

```bash Discover theme={null}
claude mcp add --transport http opus-discover https://mcp.opus.com/v1/mcp/discover \
  --header 'x-service-key: ${OPUS_API_KEY}'
```

```bash Admin theme={null}
claude mcp add --transport http opus-admin https://mcp.opus.com/v1/mcp/admin \
  --header 'x-service-key: ${OPUS_API_KEY}'
```

The single quotes stop your shell from expanding the variable. Claude Code stores the reference `${OPUS_API_KEY}`, not the key, and reads the key from the environment it starts in. It does not check the key here: a wrong key shows up only when it connects.

## Verify

Start Claude Code and ask the agent to call `list_workspaces` on `opus-build`. A list of your workspaces means the connection works.

> [!WARNING]
>
> `claude mcp list` showing **Connected** proves only that the MCP handshake worked. Always confirm with a real tool call such as `list_workspaces`.

## Choose a Scope

The `--scope` flag decides where Claude Code stores the server and where it is available:

| Scope | Flag | Available in | Stored in |
| - | - | - | - |
| Local (default) | `--scope local` | The current project, for you only | `~/.claude.json` |
| Project | `--scope project` | The current project, for everyone who clones it | `.mcp.json` in the project root |
| User | `--scope user` | All your projects | `~/.claude.json` |

For Opus, use **user** scope in most cases, so the server is available in every project:

```bash theme={null}
claude mcp add --transport http --scope user opus-build https://mcp.opus.com/v1/mcp/build \
  --header 'x-service-key: ${OPUS_API_KEY}'
```

## Share a Project Config Without the Key

Opus API keys belong to one user, so never commit a key. To share the Opus servers with your team, commit a `.mcp.json` that reads each person's key from their environment:

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

Claude Code expands `${OPUS_API_KEY}` when it loads the file. Each teammate sets `OPUS_API_KEY` to their own key, and Claude Code asks them to approve project servers the first time.

> [!NOTE]
>
> If `OPUS_API_KEY` is not set, Claude Code sends the literal text `${OPUS_API_KEY}` and the server returns `401`. `claude mcp list` shows a missing-variable warning in this case.

## Manage the Server

| Task | Command |
| - | - |
| List servers and their status | `claude mcp list` |
| Show one server's details and errors | `claude mcp get opus-build` |
| Remove a server | `claude mcp remove opus-build` |
| Check status inside a session | `/mcp` |

To change the key, set `OPUS_API_KEY` to the new key and restart Claude Code.

## Troubleshooting

> [accordion] Claude Code asks me to authenticate, or shows a Dynamic Client Registration error
>
> The Opus MCP server does not use OAuth. When the server rejects the request, Claude Code tries OAuth instead and fails with a message such as `Dynamic Client Registration rejected (HTTP 404)`.
>
> This is never an OAuth problem. The key is wrong, missing, or expired, or the server refused your organization or account. Check the key and the header name, then add the server again.

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.