Skip to main content

Quick Reference

Test Your Key Directly

Before you change client settings, check the key and your organization’s access from a terminal:
A JSON-RPC result with serverInfo means the key and organization are valid, and the problem is in the client configuration.

Errors in Detail

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.
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:
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, 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.
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.
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.
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.
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.
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.
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
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.
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.
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. Include the client you use, the URL you connect to, and the full error message. Never include your API key.