feat: add initial access token support for OAuth 2.0 Dynamic Client Registration (RFC 7591)

- Add initial_access_token parameter to OAuthClientProvider constructor
- Implement multi-level fallback for token resolution:
  1. Explicit parameter (highest priority)
  2. Provider method (initial_access_token())
  3. Environment variable (OAUTH_INITIAL_ACCESS_TOKEN)
  4. No token (existing behavior)
- Add Authorization Bearer header to registration requests when token available
- Add comprehensive test coverage for all fallback scenarios
- Update documentation with usage examples and configuration details
- Maintain full backward compatibility with existing OAuth flows

This enables clients to register with protected OAuth endpoints that require
initial access tokens per RFC 7591 Dynamic Client Registration specification.

Author: andormarkus-alcd

README.md

@@ -1497,6 +1497,7 @@ class CustomOAuthProvider(OAuthClientProvider):
 ```
 
 The fallback order is:
+
 1. Explicit `initial_access_token` parameter
 2. Provider's `initial_access_token()` method
 3. `OAUTH_INITIAL_ACCESS_TOKEN` environment variable

src/mcp/client/auth.py

@@ -323,10 +323,10 @@ async def _handle_oauth_metadata_response(self, response: httpx.Response, is_fal
 
     async def _register_client(self, initial_access_token: str | None = None) -> httpx.Request | None:
         """Build registration request or skip if already registered.
-        
+
         Supports initial access tokens for OAuth 2.0 Dynamic Client Registration according to RFC 7591.
         Uses multi-level fallback approach:
-        
+
         1. Explicit parameter (highest priority)
         2. Provider's initial_access_token() method
         3. OAUTH_INITIAL_ACCESS_TOKEN environment variable
@@ -541,7 +541,7 @@ async def initial_access_token(self) -> str | None:
         # Return constructor parameter if available
         if self._initial_access_token:
             return self._initial_access_token
-        
+
         # Subclasses can override this method to provide tokens from other sources
         return None
 

tests/client/test_auth.py

@@ -430,7 +430,7 @@ async def test_register_client_with_explicit_initial_access_token(self, oauth_pr
     @pytest.mark.anyio
     async def test_register_client_with_provider_initial_access_token(self, client_metadata, mock_storage):
         """Test client registration with provider method initial access token."""
-        
+
         class CustomOAuthProvider(OAuthClientProvider):
             async def initial_access_token(self) -> str | None:
                 return "provider-token"
@@ -460,7 +460,7 @@ async def callback_handler() -> tuple[str, str | None]:
     @pytest.mark.anyio
     async def test_register_client_explicit_overrides_provider(self, client_metadata, mock_storage):
         """Test explicit initial access token overrides provider method."""
-        
+
         class CustomOAuthProvider(OAuthClientProvider):
             async def initial_access_token(self) -> str | None:
                 return "provider-token"
@@ -511,7 +511,7 @@ async def test_register_client_without_initial_access_token(self, oauth_provider
     @pytest.mark.anyio
     async def test_initial_access_token_constructor_parameter(self, client_metadata, mock_storage):
         """Test OAuthClientProvider with initial access token constructor parameter."""
-        
+
         async def redirect_handler(url: str) -> None:
             pass