Skip to main content

Prerequisites

  • Claude Code installed
  • An Opus API key (see Authentication)
  • Your organization enabled for the Opus MCP server (see Overview)
  • The MCP URL for your Opus deployment. The examples use https://mcp.opus.com. For other deployments, ask the Opus team (see Server URLs)

Add the Server

Add one server for each category you need.
1

Store your key in an environment variable

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

Add the categories you need

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.
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: For Opus, use user scope in most cases, so the server is available in every project:

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:
.mcp.json
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.
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

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

Troubleshooting

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 for all errors.