Track upstream: MCP Client OAuth/DCR Compatibility Issues - Scope and Authentication Problems

[cbcoutinho]

MCP Client OAuth/DCR Compatibility: Scope and Authentication Issues

Summary

Common MCP clients (Claude Code, Google Gemini CLI, GitHub Copilot) have incomplete support for OAuth-enabled MCP servers, particularly when Dynamic Client Registration (DCR) is enabled. These clients fail to:

1. Request required OAuth scopes
2. Handle various OAuth discovery mechanisms
3. Work with enterprise OAuth providers that don't support DCR
4. Properly discover OAuth configuration from WWW-Authenticate headers

This significantly limits the ability of this Nextcloud MCP server to work with these clients in OAuth mode.

Impact on Nextcloud MCP Server

• OAuth mode is experimental (as documented in README.md) and faces compatibility issues with major MCP clients
• Users attempting to use OAuth with Claude Code, Gemini CLI, or Copilot may experience authentication failures
• Enterprise deployments using Azure AD/Entra ID, Okta, or other providers face additional challenges
• This is in addition to the existing upstream Nextcloud issues tracked in Track upstream: Bearer token authentication failing for app-specific APIs (user_oidc#1221) #209 (Bearer token support in user_oidc app)

Root Causes

1. Dynamic Client Registration (DCR) Requirements

Problem: Claude Code requires DCR support per RFC 7591, but:

• Many enterprise OAuth providers (Azure AD, Okta) don't support DCR
• Providers that support DCR often require pre-provisioned API keys to access the registration endpoint
• Clients don't support manual client ID/secret specification as a fallback

Example: Azure AD integration fails with:

AADSTS70011: The provided request must include a 'scope' input parameter.
The provided value for the input parameter 'scope' is not valid.

2. Scope Parameter Issues

Problem: MCP clients are not requesting proper OAuth scopes when DCR is enabled:

• Clients may not send scope parameter at all
• Clients send invalid or incomplete scope values
• No standard mechanism for MCP servers to communicate required scopes to clients

Impact: Authorization servers reject requests due to missing or invalid scopes

3. OAuth Discovery Failures

Problem: Clients fail to properly discover OAuth configuration:

• Gemini CLI: Cannot extract resource_metadata from WWW-Authenticate header, tries wrong discovery endpoint (.well-known/oauth-authorization-server instead of following the resource_metadata URL)
• Claude Code: "Immediately tries to connect to /.well-known/oauth-authorization-server and ignores the resource_metadata in the www-authenticate header"
• Inconsistent handling of RFC 8414 (OAuth Authorization Server Metadata) vs RFC 9728 (OAuth Protected Resource Metadata)

4. Architectural Design Issues

Problem: Current MCP auth implementation treats MCP servers as OAuth authorization servers, requiring every MCP server to implement:

• Discovery endpoints
• Registration endpoints
• Authorization endpoints
• Token endpoints

Proposed solution: Treat MCP servers as OAuth resource servers, allowing them to leverage existing identity providers/authorization servers (see modelcontextprotocol/modelcontextprotocol#205)

Upstream Issues

MCP Specification Repository

• #695 - Incompatible DCR Flow When registration_endpoint Requires Credentials

  • Issue: DCR incompatible with providers like Okta that require API keys for registration
  • Impact: Cannot use DCR with major enterprise OAuth providers

• #205 - Treat the MCP server as an OAuth resource server

  • Issue: Current architecture requires every MCP server to be a full OAuth authorization server
  • Proposal: Use resource server pattern to leverage existing identity providers
  • Would enable enterprise scenarios, token exchange flows, and reduce complexity

Claude Code Repository

• #2527 - Claude OAuth requires DCR, making Azure AD/Entra ID integration complex

  • Issue: Azure AD doesn't support DCR, requires pre-registered apps with fixed redirect URIs
  • Claude uses random ports requiring constant Azure AD app updates
  • Missing scope parameter causes AADSTS70011 errors

• #2267 - Cannot connect Remote GitHub MCP Server

  • Issue: Claude Code cannot authenticate with GitHub's official MCP server
  • Related to OAuth discovery and DCR issues

• #3515 - MCP OAuth Integration Fails on Production Deployments

  • Issue: OAuth flow fails immediately with step=start_error
  • Affects production MCP server deployments

• #1178 - Claude Code MCP Server OAuth doesn't work in SSH remote sessions

  • Issue: No way to access browser remotely for OAuth flow
  • Limits deployment scenarios

Google Gemini CLI Repository

• #5011 - /mcp auth github fails to discover OAuth configuration

  • Issue: Cannot extract resource_metadata from WWW-Authenticate header
  • Tries wrong discovery endpoint instead of following RFC 9728 flow
  • GitHub MCP server provides correct headers but Gemini CLI cannot parse them

• #5397 - Github MCP OAuth

  • Related OAuth issues with GitHub MCP server

FastMCP Repository

• #972 - OAuth works with MCP Inspector but not with Claude/FastMCP Client
  • Issue: OAuth works with MCP Inspector but fails with Claude Desktop and FastMCP Client
  • Error: invalid_client - "The requested OAuth 2.0 Client does not exist"
  • Indicates inconsistent OAuth behavior between different MCP clients

Technical Details

OAuth Discovery Mechanisms

The MCP specification supports multiple OAuth discovery mechanisms, but clients implement them inconsistently:

1. RFC 9728 - OAuth 2.0 Protected Resource Metadata: Server returns WWW-Authenticate header with resource_metadata URL
2. RFC 8414 - OAuth Authorization Server Metadata: Discovery at /.well-known/oauth-authorization-server

GitHub MCP Server example:

WWW-Authenticate: Bearer error="invalid_request",
  error_description="No access token was provided in this request",
  resource_metadata="https://api.githubcopilot.com/.well-known/oauth-protected-resource/mcp"

Gemini CLI fails to extract this and tries the wrong endpoint.

Scope Communication Problem

• OAuth servers need to know which scopes to grant
• MCP specification doesn't define standard scopes
• Clients don't have a mechanism to discover required scopes from MCP servers
• Some clients don't send scope parameter at all when using DCR

Provider Compatibility Matrix

Provider	DCR Support	Status	Notes
Azure AD/Entra ID	❌ No	Broken	Requires pre-registration, fixed redirect URIs
Okta	⚠️ Requires API Key	Broken	DCR endpoint requires admin credentials
AWS Cognito	❌ No	Broken	Requires custom implementation with Lambda/API Gateway
Auth0	✅ Yes	May work	DCR supported (requires testing)
Keycloak	✅ Yes	May work	DCR supported (requires testing)
GitHub	❌ Special	Complex	Uses RFC 9728 but clients fail to discover properly

Proposed Solutions (from Community)

SEP-991: Client ID Metadata Documents

• Allow OAuth clients to use HTTPS URLs as client identifiers
• URL points to JSON document with client metadata
• Addresses MCP scenarios where servers/clients have no pre-existing relationship
• Enables servers to trust clients based on verified metadata

SEP-1299: Simplified Flow

• Move OAuth flow management from MCP clients to MCP servers
• Use HTTP Message Signatures for session binding
• Resource servers could leverage existing authorization modalities

Resource Server Pattern

• Treat MCP servers as OAuth resource servers instead of authorization servers
• Leverage existing identity providers/authorization servers
• MCP server validates tokens but doesn't issue them
• Supports token exchange flows for on-behalf-of scenarios

Status & Recommendations

Current State

• ⚠️ OAuth mode in this Nextcloud MCP server is EXPERIMENTAL
• 🔴 Not recommended for production due to:
  1. Client compatibility issues (this issue)
  2. Nextcloud upstream issues (Track upstream: Bearer token authentication failing for app-specific APIs (user_oidc#1221) #209)
  3. Limited enterprise OAuth provider support

Short-term Workarounds

• ✅ Use Basic Auth mode (recommended) - works reliably with all clients
• ⚠️ For OAuth testing: Use providers with full DCR support (Auth0, Keycloak)
• ⚠️ Avoid enterprise providers (Azure AD, Okta) until client-side issues are resolved

Long-term

• 🕒 Monitor upstream MCP client repositories for OAuth improvements
• 🕒 Watch for SEP-991 and SEP-1299 standardization progress
• 🕒 Track Nextcloud user_oidc Bearer token support (Track upstream: Bearer token authentication failing for app-specific APIs (user_oidc#1221) #209)
• 🕒 Consider implementing resource server pattern when clients support it

References

Blog Posts & Documentation

• Evolving OAuth Client Registration in MCP
• Tips to Harden OAuth Dynamic Client Registration in MCP Servers
• Diving Into the MCP Authorization Specification
• Let's fix OAuth in MCP by Aaron Parecki
• MCP and OAuth Dynamic Client Registration
• Understanding OAuth2 and implementing identity-aware MCP servers

MCP Specification

• Authorization - Model Context Protocol

---

This is a tracking issue. Updates will be added as upstream issues progress and client implementations improve.

[cbcoutinho]

Additional Claude Code OAuth/PRM Scope Issues

Found two more critical open issues in the Claude Code repository related to Protected Resource Metadata (PRM) and OAuth scopes:

#7744 - Claude Code MCP client ignores scopes_supported from OAuth protected resource metadata

Status: Open (filed in Claude Code v1.0.117)

Problem: Claude Code fetches the /.well-known/oauth-protected-resource endpoint but completely ignores the scopes_supported field when constructing authorization requests.

Impact:

• Authorization requests are sent without any scope parameter
• The offline_access scope is never requested, so no refresh tokens are issued
• Users must re-authenticate every 5 minutes when access tokens expire
• Makes OAuth-based MCP servers practically unusable for development work

Debug logs show:

[DEBUG] MCP server "basic-memory": Fetched OAuth metadata with scope: NONE
[DEBUG] MCP server "basic-memory": Scopes in URL: NOT FOUND
[DEBUG] MCP server "basic-memory": No scopes available from URL or metadata
[DEBUG] MCP server "basic-memory": ERROR: No scopes stored to add to token request!
[DEBUG] MCP server "basic-memory": Has refresh token: false
[DEBUG] MCP server "basic-memory": Token expires in: 300

Expected behavior:

1. Read scopes_supported from the PRM endpoint (/.well-known/oauth-protected-resource)
2. Include those scopes in OAuth authorization requests
3. Receive refresh tokens when offline_access is supported
4. Auto-refresh tokens for persistent authentication

Note: Other Claude clients (Desktop, Web, Mobile) handle OAuth scopes correctly with the same MCP server, indicating this is a Claude Code-specific implementation issue.

---

#8001 - Dynamic Client Registration requests omit scope

Status: Open (affects Claude Desktop v0.13.19)

Problem: During Dynamic Client Registration (DCR per RFC 7591), Claude doesn't include the scope client metadata in the registration request body.

Impact:

• OAuth servers fall back to permissive defaults, registering clients with all available scopes
• Security risk: Violates the principle of least privilege
• Over-privileged clients can access more resources than needed

Expected behavior:

1. Discover scopes_supported from the PRM endpoint
2. Include only the minimum required scopes in the DCR request (least-privilege principle)
3. Ideally implement progressive/just-in-time scoping

Current behavior (observed in registration requests):

{
  "client_name": "Claude",
  "redirect_uris": ["..."],
  // scope field is MISSING
}

---

Summary

These issues complement the existing scope problems documented above:

• #2527: Missing scope parameter causes Azure AD failures
• #7744: PRM scopes_supported field is completely ignored in authorization requests
• #8001: DCR requests omit scope metadata, causing over-privileged client registrations

The root cause appears to be incomplete implementation of RFC 9728 (OAuth Protected Resource Metadata) in Claude Code's OAuth client. While the client fetches the PRM endpoint, it doesn't properly parse or use the scopes_supported information in either authorization requests or client registration.

This affects the Nextcloud MCP server's OAuth mode, as it cannot communicate required scopes (like nc:read, nc:write) to Claude Code clients, even when properly exposed via the PRM endpoint.