Fix MCP OAuth token-exchange 404 errors

Treat the 404 as a token-route failure, not failed consent

If the trace records an OAuth callback code and the next request receives HTTP 404, the observed failure is at the code-to-token boundary. That sequence does not prove every earlier step was healthy, and repeating sign-in does not prove that the client is posting to the right place. Record the exact origin and path of the failed POST, then compare it with the `token_endpoint` in the authorization server metadata the client actually retrieved.

Current MCP authorization discovery has two distinct metadata hops. The MCP server identifies one or more authorization servers through protected-resource metadata; the selected authorization server then publishes its own endpoints. A client must use that validated authorization-server metadata rather than assume that `/token` exists on the MCP resource origin. Keep the authorization code, verifier, client credentials, cookies, and tokens out of traces.

Trace the discovery chain before changing OAuth parameters

1. Preserve the initial challenge

Record `resource_metadata` without credentialsThe current MCP specification says clients use the URL from `WWW-Authenticate` when present and otherwise try the protected-resource well-known locations. A dropped challenge can make the client guess from the MCP URL.

2. Read protected-resource metadata

Identify the selected authorization-server issuerRecord the metadata URL, HTTP status, content type, `resource`, and the chosen entry from `authorization_servers`. If several issuers are listed, record which one the client selected rather than assuming a choice.

3. Read authorization-server metadata

Copy only issuer and endpoint URLsFor a path-bearing issuer, verify the MCP discovery order rather than appending one favorite well-known suffix. Reject metadata whose returned `issuer` is not identical to the issuer used for discovery.

4. Compare the outbound POST

It must target the advertised `token_endpoint`OAuth uses POST for an access-token request. Record the destination and form-field names only; redact `code`, `code_verifier`, client secrets, and any returned token values.

5. Classify the response body

A route 404 is unlike a normal OAuth rejectionRFC 6749 token errors are normally HTTP 400 with a JSON `error` value, except that invalid client authentication can use 401. A plain-text or HTML 404 strongly suggests that the request reached a route that is not acting as the token endpoint, but it does not identify which layer chose that route.

6. Check the protected resource parameter

Preserve the canonical MCP resource URICurrent MCP authorization requires the `resource` parameter in both authorization and token requests. If the advertised endpoint is reached and returns a structured OAuth error, follow that named error; do not infer a resource, redirect, code, verifier, or client-binding defect from a route 404 alone.

Use reproducible SDK records as bounded failure patterns

An open TypeScript SDK issue provides a concrete separate-authorization-server reproduction: the initial 401 advertised protected-resource metadata, but the reporter said the Streamable HTTP flow did not retain that URL before `finishAuth()`. The trace then posted to `/token` on the MCP server instead of the Cognito endpoint. An April 2026 bot comment reports the case reproduced on the v1.x branch and fixed on `main`, while saying a v1.x backport was still needed. Because the issue remains open, verify the exact SDK release and transport you run; do not convert that comment into a universal minimum-version claim.

A separate closed TypeScript SDK report tied version 1.21.1 to 404 responses while discovering Jira MCP OAuth metadata. Its reproduction showed path segments such as `/v1/` disappearing from guessed endpoint URLs, and the maintainers linked the closure to a metadata-discovery fallback change. That historical regression supports checking URL construction and version changes, but it does not prove that every current 404 is an SDK bug or that downgrading is safe.

Distinguish a wrong destination from a rejected token request

POST went to the MCP resource URL or its `/token` guess

Investigate lost or bypassed metadataCompare the request with the validated `token_endpoint`. Check whether the client persisted protected-resource and authorization-server metadata across the browser callback instead of re-deriving a destination from the server URL.

POST went to the advertised token endpoint and returned JSON

Read the OAuth errorAn `invalid_grant` response identifies an authorization-grant or redirect mismatch; `invalid_client` identifies client-authentication failure; and `invalid_request` identifies malformed request shape. Do not rewrite routes merely because token issuance failed.

Metadata was correct, but the advertised endpoint saw no POST

Compare client execution pathsAn open mcp-remote report describes version 0.1.38 proxy mode failing with a plain-text 404 while its standalone client succeeded against the same sanitized configuration. Its attached trace reportedly showed correct metadata yet no token POST at the advertised proxy endpoint. This is one project's anecdotal reproduction, not proof about other proxies.

A later client build works without a documented root cause

Record the result without guessingA closed Webflow issue reported Cursor 3.0.9 receiving a plain-text 404 after the callback; a maintainer later reported success on 3.0.16 and closed the issue. The record does not establish whether the change was client-side, server-side, configuration-related, or transient.

Apply a bounded recovery sequence

1. Stop repeated browser authorization

Keep the first complete sanitized traceOnce a sanitized trace shows the callback followed by a token POST and route 404, preserve that sequence. Another browser attempt does not verify the POST destination; first compare the failed destination with the published `token_endpoint`.

2. Re-enter the canonical MCP URL

Remove hand-added OAuth pathsStart with the MCP resource endpoint under diagnosis, not a guessed authorization, callback, registration, or token endpoint. Follow its protected-resource metadata to the authorization server, and preserve the canonical MCP resource URI in the authorization and token requests.

3. Verify metadata from the same network path

Check proxy-visible scheme, host, and pathCompare the public issuer and token endpoint with what the client logged. If the values differ across the public metadata, client trace, and server request record, report that exact mismatch rather than bypassing issuer validation or assuming which intermediary changed it.

4. Verify the exact client and SDK release

Consult release notes for the affected transportThe reviewed TypeScript SDK records concern specific Streamable HTTP or legacy discovery paths, while the open mcp-remote record contrasts its proxy and standalone-client paths. Upgrade or pin only when a maintained release explicitly covers the reproduced path; do not treat an open report or proposed workaround as a shipped fix.

5. Retry one connection

Confirm the POST reaches the published endpointAfter correcting configuration or installing a verified fix, reconnect once and compare only destination, status, content type, and redacted parameter names. If the advertised endpoint is reached and returns JSON, continue with the named OAuth error instead of this 404 guide.

Move to the guide for the first different boundary

Return to the troubleshooting directory when the failure is not specifically the authorization-code or refresh-token POST. If the observed response literally reports a missing MCP session, continue with the session-not-found guide. If the trace instead shows an HTTP GET receiving 405, continue with the GET 405 guide. A failure while retrieving protected-resource or authorization-server metadata occurs before token exchange; a structured token response from the advertised endpoint should be diagnosed by its OAuth error value.

Evidence boundary

The normative diagnosis comes from the 2026-07-28 MCP authorization and discovery requirements plus RFC 8414 and RFC 6749. The client examples are public issue records with different states: one TypeScript SDK case remains open with a reported fix on `main`, one historical regression is closed, one mcp-remote proxy report remains open, and one Webflow report closed after a later client build worked. They demonstrate reproducible wrong-route patterns, not prevalence, compatibility across all MCP clients, or a guaranteed version fix. No authenticated token exchange, production server, secret, or customer account was used.

The 2026-08-09 real last30days run returned 64 items with degraded coverage: Reddit was partial under HTTP 429, X was unconfigured, and zero retrieved items were classified relevant to this token-exchange 404 diagnosis. Failed or partial sources are not evidence that no discussion exists. Current community support therefore comes from the separately reviewed public issue records and is explicitly anecdotal. This draft cannot determine whether an unnamed 404 was introduced by client state, SDK URL construction, reverse-proxy routing, stale metadata, or authorization-server deployment without the redacted endpoint matrix.