Skip to main content

Prerequisites

  • Claude Desktop 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)

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.

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 you need, for example opus-discover with https://mcp.opus.com/v1/mcp/discover.
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 so each person uses their own key.
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 package runs on your computer and forwards requests to the Opus MCP server with your API key. It needs Node.js 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:
claude_desktop_config.json
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.
3

Restart Claude Desktop

Quit Claude Desktop completely and open it again. It loads the configuration only at startup.
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.
--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 for all errors.