MCP 503 mcp_oauth_unavailable vs 401: do not re-sign-in

An MCP client that signed in to Sume with OAuth sends a bearer token on every call to https://mcp.sume.com/mcp. If that call fails, the status code decides what the client should do. A 401 means the token is bad and a new sign-in is the right response. A 503 means the server could not check the token, and a new sign-in will not help at all.

Three answers to an OAuth token

When the token is missing, malformed, expired or not issued for this resource, the server returns 401 with the code unauthorized, and a www-authenticate header that points at the protected resource metadata URL. That header is what lets a client start the OAuth flow again.

When the server has no secret configured for hashing OAuth tokens, it returns 503 with the code mcp_oauth_not_configured and the message "MCP OAuth authentication is not configured." Any other failure while looking up the token, such as the store being down, returns 503 with mcp_oauth_unavailable and "MCP OAuth authentication is temporarily unavailable." Neither 503 carries the www-authenticate header.

Why the split matters

A client that treats every failure as an auth failure loops: it opens a browser, you approve, the next call fails with the same 503, and it opens the browser again. The fault is on the server, so another approval does not change the answer.

In your own client code, branch on the status first. Refresh or restart OAuth only on 401. On 503, back off with jitter for a few tries, then surface the error text. An API key is an alternative credential, which the MCP page documents, so you can switch to one for a stuck production job. Send only one credential header at a time.

What to check on your side

Keep the failing request id from the error body, and note the exact code. Compare it against a call with an API key. If the key works and OAuth returns mcp_oauth_unavailable, the problem is the token lookup, and a repeated sign-in is not the fix. If both fail, look at your network path first.