Prerequisites
- An MCP client that uses the Streamable HTTP transport and can send a custom header with your key (
x-service-key: <key>orAuthorization: Bearer <key>) - 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)
build category as opus-build. Add one entry per category you need, and keep your key in the OPUS_API_KEY environment variable where the client supports it.
Codex
The Codex CLI, the Codex IDE extension, and the ChatGPT desktop app share one MCP configuration in~/.codex/config.toml. Configure Opus once and it is available in all of them.
Codex reads your Opus API key from an environment variable and sends it as Authorization: Bearer <key>, so the key never appears in the configuration file:
~/.codex/config.toml
~/.codex/config.toml:
OPUS_API_KEY is set.
To send the x-service-key header instead, use env_http_headers. It maps a header name to the name of an environment variable:
~/.codex/config.toml
codex mcp list shows Auth Unsupported for the server. This is expected. Run codex mcp get opus-build to see the header mapping.
Codex also reads .codex/config.toml in a project, but only for projects you trust. Because bearer_token_env_var and env_http_headers hold only the variable name, you can commit a project file and each teammate sets OPUS_API_KEY to their own key.
To verify, run codex mcp list to confirm the server is configured, then start Codex and ask the agent to call list_workspaces. Inside the Codex TUI, /mcp shows the active servers. The Opus MCP server uses API keys only, so you do not need codex mcp login.
Cursor
Add the server to~/.cursor/mcp.json to use it in every project, or to .cursor/mcp.json in a project root to use it in that project only:
~/.cursor/mcp.json
${env:OPUS_API_KEY} with the value of the environment variable. Start Cursor from an environment where OPUS_API_KEY is set.
To verify, open Customize in the sidebar and check that opus-build is enabled, then ask the agent to call list_workspaces. If the server does not connect, open the Output panel and select MCP Logs.
Gemini CLI
Add the server to~/.gemini/settings.json (all projects) or .gemini/settings.json (one project):
~/.gemini/settings.json
$OPUS_API_KEY (or ${OPUS_API_KEY}) from your environment when it loads the settings file, so the key stays out of the file. Use httpUrl, or url with "type": "http". In Gemini CLI, a plain url without type selects the SSE transport, which Opus does not support.
You can also add the server with the CLI:
/mcp in a Gemini CLI session and check that opus-build shows as connected with its tools, then ask the agent to call list_workspaces.
Any Other Client
Streamable HTTP clients
Use these settings:
Clients that use the older SSE transport cannot connect. See Transport.
Clients that support only local (stdio) servers
Use themcp-remote bridge. It runs on your computer as a local server and forwards requests to Opus with your key. It needs Node.js 18 or later.
args, which breaks the header.
The env block holds your key in plain text in the client’s config file. Do not share or commit that 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.
To verify, ask the agent to call list_workspaces.