EmblemAI's OAuth pattern for Claude Code MCP servers

EmblemAI published a detailed guide to OAuth implementation for MCP servers that integrate with Claude Code. The post addresses a gap in MCP documentation: while MCP itself is well-documented, the OAuth requirements for user-scoped data are often overlooked, and the difference between "technically compliant" and "actually works with Claude Code" is significant.

Omitting any of these results in a cryptic "failed to install" error from Claude Code.

Claude Code's `mcp add --transport http` command expects servers to expose four key OAuth components: a discovery document at `/.well-known/oauth-authorization-server`, an authorize endpoint supporting PKCE (code_challenge + code_challenge_method=S256), a token endpoint accepting public clients (no client secret), and a JWKS endpoint at `/.well-known/jwks.json`. Loopback redirect URIs (http://127.0.0.1:*) are required for native clients. Omitting any of these results in a cryptic "failed to install" error from Claude Code.

EmblemAI's discovery document specifies `token_endpoint_auth_methods_supported: ["none"]` (correct for public clients), `client_id_metadata_document_supported: true` (RFC 7591 extension allowing clients to pass metadata URLs instead of registering), and `code_challenge_methods_supported: ["S256"]` with no plain fallback (PKCE is mandatory to prevent auth-code theft on shared machines). Tokens are RS256-signed JWTs validated against the JWKS. Refresh tokens are one-time-use; replaying a used token returns `{"error": "refresh_replayed"}`, which matters for Claude Code alternatives that must write fresh tokens to disk before subsequent requests.

EmblemAI recommends: host the OAuth server yourself (don't outsource to Auth0 for public-client MCP); support public clients with PKCE and loopback redirects; never require client secrets or pre-registration; use short-lived access tokens (~15 min) with one-time refresh tokens; and ship discovery metadata correctly on day one. PR #97 to api.emblemvault.ai implemented these endpoints, PKCE flow, RFC 7591 client metadata handling, and loopback compatibility.

Key facts

1. 01Claude Code's MCP installer requires OAuth discovery metadata at `/.well-known/oauth-authorization-server` and `/.well-known/jwks.json`; missing either causes a confusing install failure with no useful logs
2. 02Public-client MCP servers must support PKCE (S256 only, no plain fallback) and loopback redirect URIs (http://127.0.0.1:*); client secrets are incompatible with native clients like Claude Code
3. 03RFC 7591 client metadata document support (`client_id_metadata_document_supported: true`) lets clients pass a metadata URL instead of requiring pre-registration or dynamic registration
4. 04EmblemAI uses RS256-signed JWT tokens with JWKS validation; refresh tokens are one-time-use and return `refresh_replayed` error if replayed, requiring clients to write fresh tokens to disk immediately
5. 05EmblemAI recommends self-hosting OAuth servers for public-client MCP (not Auth0), using short-lived access tokens (~15 min), and shipping discovery metadata on day one

Topics