OpenX MCP Server errors and limits
This page answers what the errors from the OpenX MCP server mean and how long a connection lasts. Each tool's own refusals are on its page under Tools.
A 401
A missing, expired, invalid or revoked token answers HTTP 401. Its WWW-Authenticate header
points at the server's protected-resource metadata, which is how a browser client finds the sign-in
again. A client configured with an Authorization header does not fall back to the browser: replace
the key, or remove the header and reconnect.
Connection refusals
These come before any tool runs. The common one is the first: a token not made for this address is refused at
the door with a bare Unauthorized and a WWW-Authenticate challenge. That covers a key or sign-in for the other
address, an App Identity token, a job token and a team API key. The two coded rows after it are rarer second
checks, for a token the door let through whose contents disagree.
| Status | Code | Message | What to do |
|---|---|---|---|
| 401 | none | "Unauthorized", with WWW-Authenticate | Use an MCP sign-in or an MCP key made for this address |
| 401 | MCP_TOKEN_WORKSPACE_MISMATCH | "This token is not for this workspace address." | Rare. Connect with a token made for that address |
| 401 | MCP_TOKEN_FOREIGN_CLAIM | "Invalid bearer token." | Rare. Use an MCP sign-in or an MCP key, not an App Identity or job token |
| 401 | none | "The API refused this access token." | Reconnect (sign in again) |
| 401 | MCP_DOWNSTREAM_EXCHANGE_REFUSED | "The sign-in server refused this access token for the OpenX API." | Reconnect |
| 503 | MCP_DOWNSTREAM_EXCHANGE_REFUSED | "The sign-in server refused this server's exchange." | Tell whoever runs the MCP server |
| 503 | MCP_DOWNSTREAM_EXCHANGE_UNAVAILABLE | "The sign-in server is unavailable for the exchange." | Try again shortly |
A session that belongs to someone else
An MCP session belongs to the user who opened it. A request on another user's session is refused. Start a new session instead.
A tool error versus a connection error
A tool error is an answer: the call reached the tool, and the result is marked isError with a
message and, where there is one, a remedy. A connection error means the call never reached a tool,
such as a 401, a network failure, or the MCP unknown-tool error for a name the server does not
list.
When the api refuses
call_api, manage_proposals, get_workspace, retrieve_inventory and get_stats read the OpenX api for you,
and pass its refusal on with the remedy below. All but get_workspace also add a sentence that says what
happened, such as "The api refused the route ... (403, ...)." or "Nothing answered the route ... (404), and
no refusal code came back: that is the server's routing, not your access." get_workspace gives the remedy only.
The remedy depends on the api's code:
| Api answer | Remedy |
|---|---|
| Any 401 | "Your sign-in for this MCP server was refused. Reconnect the MCP server (sign in again), then retry." |
OXAPI_MCP_DELEGATION_NOT_ON_TEAM | You are not on this workspace's team; signing in again will not change it. Ask a workspace owner to add you |
OXAPI_REQUIRED_RIGHTS_MISSING | The connection does not carry the right it names. If you hold it, reconnect and allow it on the consent screen; if not, ask an OpenX administrator |
OXAPI_INSUFFICIENT_SCOPE | You hold the right, but this connection was not allowed to use it. Reconnect and allow it on the consent screen |
ACCESS_RIGHT_REQUIRED | You do not hold the right in this workspace. Ask a workspace owner, or someone who holds Workspace.Access.Manage |
OXAPI_SCOPE_REFUSED | "The MCP server does not make this call for anyone; do it in the OpenX app." |
OXAPI_RIGHTS_UNREADABLE, WORKSPACE_EAC_UNAVAILABLE, OXAPI_MCP_DELEGATION_TEAM_UNREADABLE | "OpenX could not check your access or read the workspace right now. Try again shortly." |
The refusal carries the api's Status, its UpstreamCode, and the MissingRights when the api named them.
The server holds no tool to a list of rights of its own today; what a tool can reach is decided by the api, with
your rights.
How long a connection lasts
A browser sign-in gives one-hour access tokens and refreshes them for up to 30 days, re-checking your rights at each refresh. An MCP key lasts the lifetime chosen when it was minted, 1 day, 7 days or 30 days, unless it is revoked first. A revoked key's tool calls stop within five minutes; until the key expires, it can still list the tools and read the prompts.
When the docs are down
browse_docs answers BROWSE_DOCS_UNAVAILABLE with the docs URL when the docs site does not
answer. The workspace guides under guides/ still answer.