Migrating MCP Server to OAuth: Implementation Guide and Client Quirks

FailOk3553 · reddit · 2026-08-10

The author shares a war story of migrating a hosted MCP (Model Context Protocol) server from simple URL token authentication to a full OAuth flow.

Motivations for Migration:

Health Probe Misinterpretation: Directory probes (like Glama, Smithery) hitting the bare URL received a 401 and marked the server as "Unhealthy". With OAuth, they see the WWW-Authenticate header and recognize it as "healthy, auth required".
Token Leakage: Tokens in URLs easily leak via screen recordings or syncing dotfiles to public repos.
Connection UX: OAuth allows users to add a bare URL and automatically opens the browser for auth, removing the token generation step where most signups died.

Key Implementation Notes & Pitfalls:

Client Differences: Claude clients use Dynamic Client Registration (DCR), while ChatGPT dev mode uses CIMD (where clientid is a URL to a metadata doc). You must support both, or one major client will silently fail.
Endpoint Separation: The authorization endpoint and token endpoint can live on separate hosts (RFC 8414), useful when web sessions are in localStorage.
Do NOT answer initialize anonymously: If the first request succeeds without auth to please health checkers, Claude treats the server as authless, skips the OAuth flow entirely, and dies at the first tool call.
Smithery's Design: Its publish pipeline pauses to hand back an authorize URL, and the scanner actually completes the OAuth flow to enumerate tools.

More from coding & agent