> ## Documentation Index
> Fetch the complete documentation index at: https://developer.opus.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect Other Clients

> Add the Opus MCP server to Codex, Cursor, Gemini CLI, or any MCP client that supports Streamable HTTP.

## 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](https://developer.opus.com/mcp/overview.md#authentication))
* Your organization enabled for the Opus MCP server (see [Overview](https://developer.opus.com/mcp/overview.md))
* The MCP URL for your Opus deployment. The examples use `https://mcp.opus.com`. For other deployments, ask the Opus team (see [Server URLs](https://developer.opus.com/mcp/overview.md#server-urls))

Each example below adds the `build` category as `opus-build`. Add one entry per [category](https://developer.opus.com/mcp/overview.md#server-urls) 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:

```toml ~/.codex/config.toml theme={null}
[mcp_servers.opus-build]
url = "https://mcp.opus.com/v1/mcp/build"
bearer_token_env_var = "OPUS_API_KEY"
```

You can also add the server with the CLI. The command writes the same entry to `~/.codex/config.toml`:

```bash theme={null}
codex mcp add opus-build --url https://mcp.opus.com/v1/mcp/build --bearer-token-env-var OPUS_API_KEY
```

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:

```toml ~/.codex/config.toml theme={null}
[mcp_servers.opus-build]
url = "https://mcp.opus.com/v1/mcp/build"
env_http_headers = { "x-service-key" = "OPUS_API_KEY" }
```

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.

> [!WARNING]
>
> 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:

```json ~/.cursor/mcp.json theme={null}
{
  "mcpServers": {
    "opus-build": {
      "url": "https://mcp.opus.com/v1/mcp/build",
      "headers": {
        "x-service-key": "${env:OPUS_API_KEY}"
      }
    }
  }
}
```

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):

```json ~/.gemini/settings.json theme={null}
{
  "mcpServers": {
    "opus-build": {
      "httpUrl": "https://mcp.opus.com/v1/mcp/build",
      "headers": {
        "x-service-key": "$OPUS_API_KEY"
      }
    }
  }
}
```

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:

```bash theme={null}
gemini mcp add --scope user --transport http \
  --header "x-service-key: $OPUS_API_KEY" \
  opus-build https://mcp.opus.com/v1/mcp/build
```

> [!WARNING]
>
> 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:

| Setting | Value |
| - | - |
| Transport | Streamable HTTP |
| URL | `https://mcp.opus.com/v1/mcp/{category}` |
| Header | `x-service-key: <your_api_key>` or `Authorization: Bearer <your_api_key>` |
| Authentication | None (no OAuth) |

Clients that use the older SSE transport cannot connect. See [Transport](https://developer.opus.com/mcp/overview.md#transport).

### Clients that support only local (stdio) servers

Use the [`mcp-remote`](https://github.com/geelen/mcp-remote) bridge. It runs on your computer as a local server and forwards requests to Opus with your key. It needs [Node.js](https://nodejs.org) 18 or later.

```json theme={null}
{
  "mcpServers": {
    "opus-build": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.opus.com/v1/mcp/build",
        "--transport",
        "http-only",
        "--header",
        "x-service-key:${OPUS_API_KEY}"
      ],
      "env": {
        "OPUS_API_KEY": "<your_api_key>"
      }
    }
  }
}
```

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](https://github.com/geelen/mcp-remote).

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](https://developer.opus.com/mcp/troubleshooting.md#test-your-key-directly). See [Troubleshooting](https://developer.opus.com/mcp/troubleshooting.md) for all errors.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.