> ## 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.

# Troubleshooting the Opus MCP Server

> Fix common connection, authentication, access, permission, and rate-limit errors with the Opus MCP server.

## Quick Reference

| Symptom | Most likely cause | Fix |
| - | - | - |
| `401` `API key is required` | The client does not send the key, or sends an empty value | Add the `x-service-key` or `Authorization: Bearer` header |
| `401` `Invalid or expired API key` | Wrong, revoked, or expired key, a key from another deployment, or an unexpanded `${OPUS_API_KEY}` | Set the environment variable, or create a new key in the Opus app of the deployment your MCP URL belongs to |
| `401` `User not authorized` | The key is valid, but the user who owns it is no longer a member of the key's organization, or no longer exists | Ask an admin to add you back to the organization, or create a key in an organization you belong to |
| OAuth prompt, or `Dynamic Client Registration rejected (HTTP 404)` | The server rejected the key, or refused the organization or account | Fix the key or request organization access. Not an OAuth problem |
| `403` `Your organization is not trusted to perform this action` | Your organization is not enabled for MCP | Contact your Opus account team to request access |
| `403` `Your account has been suspended.` | The user who owns the key is suspended | Contact your organization admin |
| `403` `Your access could not be verified right now. Please try again shortly.` | Opus could not check the account of the user who owns the key | Retry after a short wait. If it persists, contact Opus support |
| Tool missing from the tool list | Your role does not allow it | Ask an admin for a role with that permission |
| Tool error `permission_denied` | Your role does not allow that tool | Ask an admin for a role with that permission |
| `400` that lists categories | URL has no category, or an unknown one | Use `/v1/mcp/build`, `/v1/mcp/discover`, or `/v1/mcp/admin` |
| `405` `Method not allowed` (with a valid key) | The client uses the SSE transport | Switch the client to Streamable HTTP |
| `429`, or tool error `rate_limited` | Too many requests for this API key | Wait for `Retry-After` or `retry_after_seconds`, then retry |
| Client shows Connected, but tools fail | Handshake only, not a tool call | Call `list_workspaces` and read the error |

## Test Your Key Directly

Before you change client settings, check the key and your organization's access from a terminal:

```bash theme={null}
curl -sS -X POST https://mcp.opus.com/v1/mcp/build \
  -H "x-service-key: $OPUS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'
```

A JSON-RPC result with `serverInfo` means the key and organization are valid, and the problem is in the client configuration.

## Errors in Detail

> [accordion] 401: API key is required, Invalid or expired API key, or User not authorized
>
> The server checks the key on every request.
>
> * **API key is required**: the client did not send the header, or sent it with an empty value. Check the header name (`x-service-key`) and that any environment variable in your config is set. Some clients send an empty value when the variable is unset.
> * **Invalid or expired API key**: the key is wrong, was revoked, or has expired. Create a new key at **API Keys** (`/app/dashboard/api-keys`) in the Opus app. This error also comes back when the client sends the literal text `${OPUS_API_KEY}` because the variable is not set. Set the variable in the environment that starts your client, then restart the client.
> * **User not authorized**: the key is valid, but the user who owns it is no longer a member of the key's organization, or no longer exists. Ask an organization admin to add you back, or create a key in an organization you belong to.
>
> Keys belong to one deployment. A key created in another Opus deployment returns `401`. Check that the MCP URL matches the deployment where you created the key. If you are not sure of your MCP URL, ask the Opus team.

> [accordion] OAuth prompt or Dynamic Client Registration error
>
> Some clients, including Claude Code and `mcp-remote`, try OAuth when a server rejects a request. The Opus MCP server does not support OAuth, so the attempt fails with a message such as:
>
> ```text theme={null}
> Dynamic Client Registration rejected (HTTP 404)
> ```
>
> This message always means one of two things:
>
> * The API key is missing, wrong, or expired (the server answered `401`).
> * The server refused your organization or account (the server answered `403`). See the `403` entries below.
>
> It is never an OAuth configuration problem. Do not try to sign in or register an OAuth client. Test the key with the request in [Test Your Key Directly](#test-your-key-directly), fix the key, and add the server again. If you use `mcp-remote`, also delete its cached credentials with `rm -rf ~/.mcp-auth` and restart your client.

> [accordion] 403: Your organization is not trusted to perform this action
>
> The Opus MCP server is enabled per organization. Your key is valid, but your organization is not enabled yet.
>
> Contact your Opus account team to request access.

> [accordion] 403: Your account has been suspended
>
> The key is valid, but the Opus user who created it is suspended. The server refuses every request made with that user's keys, with `403` and a message such as `Your account has been suspended.`
>
> Contact your organization admin.

> [accordion] 403: Your access could not be verified right now
>
> The key is valid, but Opus could not check the account of the Opus user who created it. Rather than guess, the server refuses the request with `403` and the message `Your access could not be verified right now. Please try again shortly.` This is a temporary condition. It does not mean that the account is suspended.
>
> Retry after a short wait. If the error persists, contact Opus support at [support@opus.com](mailto:support@opus.com).

> [accordion] A tool is missing, or a call returns permission\_denied
>
> The server applies your Opus role to every tool:
>
> * The tool list shows only the tools your role allows.
> * A call to a tool your role does not allow returns a tool error with `code: "permission_denied"`. The message names the permission the tool requires.
>
> Ask your agent to list its Opus tools (or call `list_tools`) to see every tool your key can use. To get access to more tools, ask an organization or workspace admin to change your role.
>
> Also check the category. Each URL exposes only the tools of its own category plus a few basic tools.

> [accordion] 400: a list of categories
>
> The URL has no category, for example `https://mcp.opus.com/v1/mcp`, or a category that does not exist. Add a category to the URL:
>
> * `https://mcp.opus.com/v1/mcp/build`
> * `https://mcp.opus.com/v1/mcp/discover`
> * `https://mcp.opus.com/v1/mcp/admin`
>
> The `400` message also lists `core`. `https://mcp.opus.com/v1/mcp/core` is a valid URL, but it gives only the basic tools that every category already includes.

> [accordion] 405: Method not allowed
>
> The Opus MCP server is stateless and accepts only `POST`. With a valid key, a `GET` or `DELETE` returns `405`. The server checks the key first, so without a valid key the same request returns `401`.
>
> This usually means the client uses the older SSE transport, which opens a stream with `GET`. Configure the client for Streamable HTTP:
>
> * Claude Code: `--transport http`
> * VS Code: `"type": "http"`
> * Gemini CLI: `httpUrl`, or `url` with `"type": "http"`
> * `mcp-remote`: `--transport http-only`

> [accordion] 429 or rate\_limited
>
> MCP and REST API calls share one rate limit per API key, and every MCP request counts, including `initialize` and `tools/list`.
>
> * A rate-limited tool call returns a tool error with `code: "rate_limited"` and `retry_after_seconds`. Retry after that many seconds. For write tools, retry with the same `operation_id`: the change runs only once.
> * Any other rate-limited request returns HTTP `429` with a `Retry-After` header.
>
> If you run several agents or scripts with the same key, they share the limit.

> [accordion] The client shows Connected, but tools fail
>
> A **Connected** status, for example in `claude mcp list`, proves only that the MCP handshake worked. Always confirm with a real tool call: ask the agent to call `list_workspaces`.
>
> Any valid key can call `list_workspaces`. If it works but other tools fail, read the error code: `permission_denied` is your role, and `rate_limited` is the rate limit. If `list_workspaces` fails too, test the key with the request in [Test Your Key Directly](#test-your-key-directly).

> [accordion] A retry returns idempotency\_conflict or operation\_in\_progress
>
> Write tools take an `operation_id` so that a retry does not apply a change twice.
>
> * `idempotency_conflict`: the same `operation_id` was used before with a different tool or different arguments. Use a new `operation_id` for a new change.
> * `operation_in_progress`: the first call with this `operation_id` is still running. Call `get_operation` with the same ID to read its progress and result.

## Still Stuck?

Contact [support@opus.com](mailto:support@opus.com). Include the client you use, the URL you connect to, and the full error message. Never include your API key.


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