Fix OfflineCreator MCP OAuth discovery failures

Start with the supported remote OAuth path

Recommended remote connection

Use https://mcp.offlinecreatorstudio.com/mcpOfflineCreator's current package documentation identifies this as the Streamable HTTP endpoint with OAuth. Configure the URL exactly, without an API key, query string, alternate hostname, or copied authorization endpoint.

First unauthenticated response

Expect a 401 Bearer challenge before browser authorizationA live initialize request on 2026-08-08 returned HTTP 401 with an empty body and a WWW-Authenticate header. The header named the protected-resource metadata URL and advertised the models, read, and generate scopes. That first 401 is discovery input, not proof that a saved password or token is wrong.

Documented fallback

Use local stdio only when remote OAuth is unsuitableThe package README documents a scoped OFFLINECREATOR_API_KEY for local stdio and a legacy bearer-header route. It explicitly warns against putting the key in the URL. Do not switch transports until you have identified which discovery request failed, because switching can conceal a client or proxy problem.

Trace OAuth discovery one public hop at a time

Preserve the status and sanitized WWW-Authenticate parameters from the first request. The current challenge points to https://mcp.offlinecreatorstudio.com/.well-known/oauth-protected-resource/mcp. Fetch that public JSON document without adding an Authorization header. It currently identifies the MCP URL as the resource, names https://mcp.offlinecreatorstudio.com as the authorization server, lists models, read, and generate as supported scopes, and allows bearer tokens in the header.

Next fetch the issuer's authorization-server metadata at https://mcp.offlinecreatorstudio.com/.well-known/oauth-authorization-server. The current document publishes authorization, token, dynamic registration, and revocation endpoints; authorization-code and refresh-token grants; and S256 proof-key support. A failure before this document is obtained is still discovery. A browser callback, authorization-code, token-exchange, or refresh failure happens later and should be diagnosed separately.

The unique output of this runbook is the first broken public hop: challenge header, protected-resource document, or authorization-server document. Record the last URL that returned valid metadata and the first response that was missing, rewritten, mismatched, or blocked. Do not rotate a credential when no token exchange has happened yet.

Map the visible symptom to the failed boundary

If all metadata checks pass and the browser opens, stop calling the problem discovery. Move the report to callback, code exchange, token validation, or scope handling with the successful metadata trace attached. That handoff keeps this page separate from the 401 status guide, which decides what an unauthenticated or invalid-token response means.

401 includes resource_metadata

Continue discoveryCurrent MCP guidance tells clients to parse the challenge, retrieve protected-resource metadata, discover the authorization server, and only then begin browser authorization. Repeatedly retrying initialize without following the metadata URL cannot complete that sequence.

Metadata request is 404, HTML, redirected, or blocked

Check the configured hostname, path, proxy, and networkCompare the requested URL with the live public URLs in this guide. A captive portal, TLS interception, proxy rewrite, DNS filter, or client that drops the challenge header can make a healthy endpoint look undiscoverable. Do not disable certificate validation as a workaround.

Protected-resource metadata returns a different resource

Stop and reject the documentRFC 9728 requires the metadata resource value discovered through resource_metadata to be identical to the resource URL the client requested. The current OfflineCreator values both resolve to https://mcp.offlinecreatorstudio.com/mcp.

Authorization-server metadata returns a different issuer

Stop before opening sign-inRFC 8414 requires the returned issuer to match the issuer used to derive the metadata URL. A mismatch is not a clock-skew problem and must not be bypassed.

Browser authorization opens, then fails

Discovery succeeded; inspect the later OAuth stepRecord whether the failure is at redirect, callback, code exchange, or refresh. Current MCP guidance uses PKCE and includes the protected resource in authorization and token requests, so an invalid_target or verifier problem belongs after metadata discovery.

Authenticated request returns 403

Treat it as a permission boundaryThe current MCP specification separates authorization-required or invalid-token 401 responses from insufficient-permission 403 responses. Reconnect for the needed scope rather than restarting metadata discovery.

Use a bounded recovery checklist

1. Re-enter the canonical endpoint

Remove trailing additions and alternate hostsSet the remote server URL to https://mcp.offlinecreatorstudio.com/mcp exactly. Do not append a metadata path, authorization path, token path, api_key parameter, or access token.

2. Capture the challenge safely

Keep status, header names, metadata URL, and scopesRemove cookies, Authorization values, authorization codes, PKCE verifiers, client secrets, and account data. The response body may be empty; the discovery pointer is in WWW-Authenticate.

3. Test both public metadata URLs

Require HTTPS JSON and exact identity matchesConfirm that protected-resource metadata returns the canonical resource and issuer, then confirm that authorization-server metadata returns the same issuer and HTTPS endpoints. A client clock problem is plausible only when certificate validity or signed-time checks actually report a time error.

4. Reload the client connection once

Retry after correcting configuration or network handlingUse the client's normal disconnect, reconnect, or server reload control. Avoid repeated generation requests while authentication is unresolved; verify only that discovery reaches browser authorization.

5. Escalate with the failing hop

Name the last successful URL and first failing responseA useful report says whether initialize, protected-resource metadata, authorization-server metadata, browser redirect, callback, or token exchange failed. This is more actionable than reporting only an OAuth discovery error string.

Choose the next guide from the first failing hop

Return to the troubleshooting directory if the failure is not confined to OAuth. Use the query-key guide when a secret was placed in the URL. Use the insufficient-scope guide when authentication completed but a tool call returns 403. This page owns only the path from the initial challenge through protected-resource and authorization-server metadata.

Evidence boundary for this research draft

The directly observed product boundary is narrow: a credential-free initialize POST returned 401 with a zero-byte body and a Bearer challenge that named the canonical protected-resource metadata URL and models, read, and generate scopes. The two public metadata documents identify the canonical resource and issuer, publish the current OAuth endpoints, and advertise S256 support. OfflineCreator's package README identifies the same MCP URL as the recommended remote OAuth route.

This draft does not claim that an authenticated request, browser callback, token exchange, refresh, revocation, client-specific cache, proxy interception, or clock-skew scenario succeeds or fails. It makes no community sentiment, workaround, benchmark, success-rate, or customer-outcome claim. Its troubleshooting sequence is limited to the observed public challenge and metadata plus the validation and authorization requirements in the cited MCP specification and OAuth RFCs.