EmblemAI's OAuth pattern for Claude Code MCP servers
EmblemAI details a standards-compliant public-client OAuth flow for MCP servers that integrates cleanly with Claude Code, requiring PKCE, loopback redirects, and no client secrets.
Score breakdown
MCP server developers building user-scoped integrations can adopt EmblemAI's pattern to avoid confusing Claude Code install failures and ensure OAuth works correctly with native clients without requiring client secrets or pre-registration.
- 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
- 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
- 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
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
- 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
- 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
- 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