Skip to main content

Prerequisites

  • An MCP client that uses the Streamable HTTP transport and can send a custom header with your key (x-service-key: <key> or Authorization: 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)
Each example below adds the 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
You can also add the server with the CLI. The command writes the same entry to ~/.codex/config.toml:
Start Codex from an environment where 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
With this form, 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 supports http_headers, which stores a literal header value in the file. Do not put your API key in http_headers: use bearer_token_env_var or env_http_headers so the key stays out of config.toml.
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
Cursor replaces ${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
Gemini CLI resolves $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:
Your shell expands $OPUS_API_KEY before Gemini CLI runs, so this command stores the key in plain text in settings.json. To keep the key out of the file, use the settings.json form above.
To verify, run /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 the mcp-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.
Keep no spaces around the colon in the header argument. Some clients do not escape spaces in 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.

Troubleshooting

To check your key and your organization’s access without an MCP client, use the request in Test Your Key Directly. See Troubleshooting for all errors.