Quick Reference
Test Your Key Directly
Before you change client settings, check the key and your organization’s access from a terminal:serverInfo means the key and organization are valid, and the problem is in the client configuration.
Errors in Detail
OAuth prompt or Dynamic Client Registration error
OAuth prompt or Dynamic Client Registration error
Some clients, including Claude Code and This message always means one of two things:
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:- The API key is missing, wrong, or expired (the server answered
401). - The server refused your organization or account (the server answered
403). See the403entries below.
mcp-remote, also delete its cached credentials with rm -rf ~/.mcp-auth and restart your client.403: Your organization is not trusted to perform this action
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.
403: Your account has been suspended
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.403: Your access could not be verified right now
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.A tool is missing, or a call returns permission_denied
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.
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.400: a list of categories
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/buildhttps://mcp.opus.com/v1/mcp/discoverhttps://mcp.opus.com/v1/mcp/admin
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.405: Method not allowed
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, orurlwith"type": "http" mcp-remote:--transport http-only
429 or rate_limited
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"andretry_after_seconds. Retry after that many seconds. For write tools, retry with the sameoperation_id: the change runs only once. - Any other rate-limited request returns HTTP
429with aRetry-Afterheader.
The client shows Connected, but tools fail
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.A retry returns idempotency_conflict or operation_in_progress
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 sameoperation_idwas used before with a different tool or different arguments. Use a newoperation_idfor a new change.operation_in_progress: the first call with thisoperation_idis still running. Callget_operationwith the same ID to read its progress and result.