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
~/.zshrc) so it is set in every terminal.2
Add the categories you need
${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 calllist_workspaces on opus-build. A list of your workspaces means the connection works.
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
${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
Claude Code asks me to authenticate, or shows a Dynamic Client Registration error
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.