Fix a 401 from the OfflineCreator MCP endpoint

Treat the first 401 as an OAuth discovery signal

A 401 from the recommended OfflineCreator endpoint is not automatically a broken credential. An unauthenticated initialize request to https://mcp.offlinecreatorstudio.com/mcp returned HTTP 401 with an empty body and a Bearer WWW-Authenticate challenge. The challenge identified the protected-resource metadata URL and advertised the models, read, and generate scopes. This is the expected starting boundary for a client that has not signed in yet.

The next action depends on what happened after that challenge. If the client opens browser authorization, continue the sign-in and consent flow. If it repeatedly shows the same unauthenticated 401 without opening authorization, inspect discovery support and the exact challenge header. If a previously working connection starts returning 401, reconnect so the client obtains a new token instead of repeatedly sending the old one.

This runbook owns the status-code decision after the response arrives. First contact with no token can be a discovery challenge; a previously authorized request returning 401 calls for fresh authorization; a valid token lacking authority belongs on the 403 path. It does not own a complete metadata-hop diagnosis. If the client cannot follow the challenge, move to the OAuth discovery runbook instead of repeating the entire discovery sequence here.

Follow the challenge before changing credentials

1. Confirm the canonical URL

Use https://mcp.offlinecreatorstudio.com/mcp for remote OAuthOfflineCreator's live connection page and published package README identify this Streamable HTTP endpoint as the recommended remote path. Do not substitute the legacy hostname while diagnosing the OAuth flow.

2. Preserve the first response

Record status and WWW-Authenticate, but never the tokenThe verified unauthenticated response was 401 with Bearer realm OAuth, a resource_metadata URL, and scope models read generate. Its empty response body means the actionable information is in the header.

3. Fetch protected-resource metadata

Check the resource, issuer, scopes, and bearer methodThe advertised document currently identifies the MCP endpoint as its resource, lists https://mcp.offlinecreatorstudio.com as the authorization server, lists models, read, and generate, and supports bearer tokens in the header.

4. Continue authorization-server discovery

Resolve the issuer's metadata before browser sign-inThe issuer metadata currently publishes authorization, token, registration, and revocation endpoints, authorization-code and refresh-token grants, and S256 proof-key support. Let the MCP client consume this metadata rather than manually constructing token requests.

5. Reconnect and retry one read-only boundary

Complete browser sign-in, then verify the connectionReload or reconnect the server through the client's normal control. A successful authorization should replace the discovery-only request with an authenticated MCP exchange. Avoid generation retries until authentication itself succeeds.

Separate missing, invalid, and under-scoped authorization

Use the request timeline to select one branch. No prior sign-in plus a challenge means continue authorization. A prior working session plus 401 means invalidate the stale credential and reconnect. A 403 after successful authentication means preserve the current grant and request only the missing scope. This status triage is complete before investigating metadata content.

No token on the first request

401 can be the normal discovery entry pointFollow resource_metadata and the issuer metadata. RFC 6750 says a request with no authentication information should not include an OAuth error code, which matches the verified OfflineCreator challenge.

Expired, revoked, malformed, or wrong-audience token

401 means obtain a fresh valid tokenThe MCP authorization specification requires invalid or expired access tokens to receive 401. Reconnect through the client; do not copy a bearer token into chat, a URL, or a support record.

Valid token lacks a required scope

Expect 403 and an insufficient_scope challengeCurrent MCP guidance distinguishes insufficient permission from missing authentication. Request only the needed additional scope through the client's authorization flow instead of treating every authorization failure as a 401.

Legacy API-key fallback

Use the documented header or stdio environment variableThe package README documents Authorization: Bearer for the legacy remote endpoint and OFFLINECREATOR_API_KEY for local stdio. It explicitly says not to put a key in the URL or use an api_key query parameter.

Validate discovery metadata before trusting it

Do not follow an arbitrary metadata URL merely because it appears in a challenge. RFC 9728 requires the resource value in metadata obtained through resource_metadata to be identical to the resource URL the client requested. The current OfflineCreator document passes that check: both values are https://mcp.offlinecreatorstudio.com/mcp.

The MCP client must parse WWW-Authenticate when it is present and must also support well-known protected-resource metadata discovery when it is absent. A client that displays the 401 but never requests metadata may lack the current remote OAuth behavior, may be using the wrong transport configuration, or may have intercepted headers. Confirm the client version and its remote MCP authorization support before changing server-side credentials.

Do not turn a 401 into a credential leak

OfflineCreator's published setup guidance says not to paste a Studio API key into chat and not to place a fallback key in the endpoint URL, an api_key query parameter, or source control. The recommended remote configuration contains only the canonical URL and uses browser OAuth. The documented legacy remote fallback sends the key in an Authorization: Bearer header, while local stdio reads OFFLINECREATOR_API_KEY from its environment.

When checking the 401 discovery path, compare the protected-resource metadata resource value with the endpoint the client requested. RFC 9728 requires clients to reject that metadata when the values differ. The current OfflineCreator metadata identifies the same canonical MCP URL observed in the credential-free initialize request.

Choose the next guide from the failing boundary

Return to the troubleshooting directory when the failure is not clearly authentication. Use the query-key guide when a key appears in the endpoint URL or a QUERY_API_KEY_FORBIDDEN response is present. The 401 guide owns the canonical endpoint challenge, metadata checks, and the distinction between first-contact discovery and an invalid token.

Evidence boundary

This draft is based on a live unauthenticated request to the canonical endpoint, its public OAuth metadata, current OfflineCreator product and package documentation, and current MCP and OAuth standards. The recent community search produced unrelated 401 and troubleshooting matches, so no practitioner anecdote, sentiment, success rate, or client-specific workaround is presented as evidence. No authenticated production request was made.