Return HTTP 401 for credential/authorization failures instead of isError: true, so OAuth clients can refresh #3677

Summary

When the GitHub API rejects a request with 401 Unauthorized (expired or invalid credential), the server currently returns it as a tool execution error: HTTP 200, isError: true, with the failure in the text content (e.g. failed to get user: GET .../user: 401 Bad credentials []).

For ordinary tool failures (validation errors, business-logic errors, 404s, 409s) this is correct and should stay — an LLM needs to see them and self-correct.

But an authorization failure is categorically different: it is not something the model can fix by adjusting arguments. It means the credential is no longer valid and the client must re-authenticate or refresh its token. We propose the server return HTTP 401 for credential/authorization failures, while keeping isError: true for all other tool errors.

Why auth failures belong at the transport layer

The MCP spec has two distinct error-handling sections, for two distinct layers:

1. Tool error handling — for failures the model can act on. These are isError: true in a 200. Correct for validation, business logic, "not found", etc.

2. Authorization error handling — for credential validity. This section is unambiguous:

   Invalid or expired tokens MUST receive a HTTP 401 response.

An expired token is precisely "invalid or expired token." The spec says that MUST be a 401. The only reason it currently isn't is an implementation detail: the credential happens to be validated downstream (at the GitHub API) rather than at the MCP server's own boundary. But from the client's perspective the meaning is identical — the token it presented is no longer good — and the spec's prescribed signal for that is HTTP 401, not a tool-result flag.

Routing auth failures through the tool-result path effectively hides a transport-layer condition inside an application-layer channel. The client's token-refresh logic lives at the transport layer (as the spec directs), so it never sees the signal.

Relationship to #420

We're aware of #420, which moved failed API calls from Go errors to isError: true. That change was correct for the general case and we're not asking to revert it. We're asking to carve out one specific sub-case — HTTP 401 from the GitHub API — and map it to the corresponding HTTP status, because the authorization spec explicitly governs that sub-case and overrides the general tool-error guidance for it.

Concretely:

Why this matters — our deployment

We host the GitHub MCP server for GitHub Enterprise Server. GHES lacks the OAuth extensions MCP needs, so we front it with a Proxy that presents a compliant Authorization Server.

• Tokens are GitHub App user-to-server tokens issued by GHES — short-lived, with refresh tokens. Mid-session expiry is the normal case.
• The Proxy is an Authorization Server only — not in the request path — so it cannot observe tool calls or emit the 401. The MCP server is the only component positioned to surface the auth failure to the client.

When the token expires, the only symptom today is a tool call returning 401 Bad credentials inside an isError: true result. Clients that follow the spec and watch for transport-level 401 never refresh.

Affected clients

OAuth-authenticating MCP clients are affected, including Joule Work and OpenCode. They implement the spec-mandated behavior of refreshing their token on a transport-level HTTP 401, but because this failure mode never produces a transport-level 401 — it arrives as isError: true in an HTTP 200 — the refresh is never triggered. The expired token keeps being replayed and every GitHub call fails, while the connection appears healthy.

Returning HTTP 401 means these clients work with no client-side changes, because they already implement the spec-mandated 401→refresh path.

The ask

Map GitHub API 401 → MCP HTTP 401, ideally with a WWW-Authenticate header, while leaving all other tool failures as isError: true. This aligns with the authorization spec's MUST, fixes OAuth token refresh for any spec-compliant client without client-side changes, and preserves #420's behavior for the error classes it was actually about.

Questions for maintainers:

1. Would you accept auth (401) being treated as a transport/authorization-layer condition rather than a tool-execution error, given the authorization spec's explicit MUST?
2. If full HTTP-status mapping is undesirable, would a hybrid be acceptable — HTTP 401 plus retain isError: true content for the LLM — so both layers get their signal?