implement-rfc-8693-token-exchange-in-mcp-sdk

Add OAuth token exchange support

Author: SoldierSacha

README.md

@@ -814,7 +814,11 @@ async def main():
 The SDK includes [authorization support](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization) for connecting to protected MCP servers:
 
 ```python
-from mcp.client.auth import OAuthClientProvider, TokenStorage
+from mcp.client.auth import (
+    OAuthClientProvider,
+    TokenExchangeProvider,
+    TokenStorage,
+)
 from mcp.client.session import ClientSession
 from mcp.client.streamable_http import streamablehttp_client
 from mcp.shared.auth import OAuthClientInformationFull, OAuthClientMetadata, OAuthToken
@@ -854,6 +858,20 @@ async def main():
     # For machine-to-machine scenarios, use ClientCredentialsProvider
     # instead of OAuthClientProvider.
 
+    # If you already have a user token from another provider,
+    # you can exchange it for an MCP token using TokenExchangeProvider.
+    token_exchange_auth = TokenExchangeProvider(
+        server_url="https://api.example.com",
+        client_metadata=OAuthClientMetadata(
+            client_name="My Client",
+            redirect_uris=["http://localhost:3000/callback"],
+            grant_types=["urn:ietf:params:oauth:grant-type:token-exchange"],
+            response_types=["code"],
+        ),
+        storage=CustomTokenStorage(),
+        subject_token_supplier=lambda: "user_token",
+    )
+
     # Use with streamable HTTP client
     async with streamablehttp_client(
         "https://api.example.com/mcp", auth=oauth_auth

src/mcp/client/auth.py

@@ -678,3 +678,90 @@ async def async_auth_flow(
 
         if response.status_code == 401:
             self._current_tokens = None
+
+
+class TokenExchangeProvider(ClientCredentialsProvider):
+    """OAuth2 token exchange based on RFC 8693."""
+
+    def __init__(
+        self,
+        server_url: str,
+        client_metadata: OAuthClientMetadata,
+        storage: TokenStorage,
+        subject_token_supplier: Callable[[], Awaitable[str]],
+        subject_token_type: str = "urn:ietf:params:oauth:token-type:access_token",
+        actor_token_supplier: Callable[[], Awaitable[str]] | None = None,
+        actor_token_type: str | None = None,
+        audience: str | None = None,
+        resource: str | None = None,
+        timeout: float = 300.0,
+    ):
+        super().__init__(server_url, client_metadata, storage, timeout)
+        self.subject_token_supplier = subject_token_supplier
+        self.subject_token_type = subject_token_type
+        self.actor_token_supplier = actor_token_supplier
+        self.actor_token_type = actor_token_type
+        self.audience = audience
+        self.resource = resource
+
+    async def _request_token(self) -> None:
+        if not self._metadata:
+            self._metadata = await _discover_oauth_metadata(self.server_url)
+
+        client_info = await self._get_or_register_client()
+
+        if self._metadata and self._metadata.token_endpoint:
+            token_url = str(self._metadata.token_endpoint)
+        else:
+            auth_base_url = _get_authorization_base_url(self.server_url)
+            token_url = urljoin(auth_base_url, "/token")
+
+        subject_token = await self.subject_token_supplier()
+        actor_token = (
+            await self.actor_token_supplier() if self.actor_token_supplier else None
+        )
+
+        token_data = {
+            "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
+            "client_id": client_info.client_id,
+            "subject_token": subject_token,
+            "subject_token_type": self.subject_token_type,
+        }
+
+        if client_info.client_secret:
+            token_data["client_secret"] = client_info.client_secret
+
+        if actor_token:
+            token_data["actor_token"] = actor_token
+        if self.actor_token_type:
+            token_data["actor_token_type"] = self.actor_token_type
+        if self.audience:
+            token_data["audience"] = self.audience
+        if self.resource:
+            token_data["resource"] = self.resource
+        if self.client_metadata.scope:
+            token_data["scope"] = self.client_metadata.scope
+
+        async with httpx.AsyncClient() as client:
+            response = await client.post(
+                token_url,
+                data=token_data,
+                headers={"Content-Type": "application/x-www-form-urlencoded"},
+                timeout=30.0,
+            )
+
+        if response.status_code != 200:
+            raise Exception(
+                f"Token request failed: {response.status_code} {response.text}"
+            )
+
+        token_response = OAuthToken.model_validate(response.json())
+        await self._validate_token_scopes(token_response)
+
+        if token_response.expires_in:
+            self._token_expiry_time = time.time() + token_response.expires_in
+        else:
+            self._token_expiry_time = None
+
+        await self.storage.set_tokens(token_response)
+        self._current_tokens = token_response

src/mcp/server/auth/handlers/register.py

@@ -78,6 +78,7 @@ async def handle(self, request: Request) -> Response:
         valid_sets = [
             {"authorization_code", "refresh_token"},
             {"client_credentials"},
+            {"urn:ietf:params:oauth:grant-type:token-exchange"},
         ]
 
         if grant_types_set not in valid_sets:
@@ -86,7 +87,7 @@ async def handle(self, request: Request) -> Response:
                     error="invalid_client_metadata",
                     error_description=(
                         "grant_types must be authorization_code and refresh_token "
-                        "or client_credentials"
+                        "or client_credentials or token exchange"
                     ),
                 ),
                 status_code=400,

src/mcp/server/auth/handlers/token.py

@@ -55,16 +55,39 @@ class ClientCredentialsRequest(BaseModel):
     client_secret: str | None = None
 
 
+class TokenExchangeRequest(BaseModel):
+    """RFC 8693 token exchange request."""
+
+    grant_type: Literal["urn:ietf:params:oauth:grant-type:token-exchange"]
+    subject_token: str = Field(..., description="Token to exchange")
+    subject_token_type: str = Field(..., description="Type of the subject token")
+    actor_token: str | None = Field(None, description="Optional actor token")
+    actor_token_type: str | None = Field(
+        None, description="Type of the actor token if provided"
+    )
+    resource: str | None = None
+    audience: str | None = None
+    scope: str | None = None
+    client_id: str
+    client_secret: str | None = None
+
+
 class TokenRequest(
     RootModel[
         Annotated[
-            AuthorizationCodeRequest | RefreshTokenRequest | ClientCredentialsRequest,
+            AuthorizationCodeRequest
+            | RefreshTokenRequest
+            | ClientCredentialsRequest
+            | TokenExchangeRequest,
             Field(discriminator="grant_type"),
         ]
     ]
 ):
     root: Annotated[
-        AuthorizationCodeRequest | RefreshTokenRequest | ClientCredentialsRequest,
+        AuthorizationCodeRequest
+        | RefreshTokenRequest
+        | ClientCredentialsRequest
+        | TokenExchangeRequest,
         Field(discriminator="grant_type"),
     ]
 
@@ -232,6 +255,27 @@ async def handle(self, request: Request):
                         )
                     )
 
+            case TokenExchangeRequest():
+                scopes = token_request.scope.split(" ") if token_request.scope else []
+                try:
+                    tokens = await self.provider.exchange_token(
+                        client_info,
+                        token_request.subject_token,
+                        token_request.subject_token_type,
+                        token_request.actor_token,
+                        token_request.actor_token_type,
+                        scopes,
+                        token_request.audience,
+                        token_request.resource,
+                    )
+                except TokenError as e:
+                    return self.response(
+                        TokenErrorResponse(
+                            error=e.error,
+                            error_description=e.error_description,
+                        )
+                    )
+
             case RefreshTokenRequest():
                 refresh_token = await self.provider.load_refresh_token(
                     client_info, token_request.refresh_token

src/mcp/server/auth/provider.py

@@ -80,6 +80,7 @@ class AuthorizeError(Exception):
     "unauthorized_client",
     "unsupported_grant_type",
     "invalid_scope",
+    "invalid_target",
 ]
 
 
@@ -253,6 +254,20 @@ async def exchange_client_credentials(
         """Exchange client credentials for an access token."""
         ...
 
+    async def exchange_token(
+        self,
+        client: OAuthClientInformationFull,
+        subject_token: str,
+        subject_token_type: str,
+        actor_token: str | None,
+        actor_token_type: str | None,
+        scope: list[str] | None,
+        audience: str | None,
+        resource: str | None,
+    ) -> OAuthToken:
+        """Exchange an external token for an MCP access token."""
+        ...
+
     async def load_access_token(self, token: str) -> AccessTokenT | None:
         """
         Loads an access token by its token.

src/mcp/server/auth/routes.py

@@ -168,6 +168,7 @@ def build_metadata(
             "authorization_code",
             "refresh_token",
             "client_credentials",
+            "urn:ietf:params:oauth:grant-type:token-exchange",
         ],
         token_endpoint_auth_methods_supported=["client_secret_post"],
         token_endpoint_auth_signing_alg_values_supported=None,

src/mcp/shared/auth.py

@@ -13,6 +13,7 @@ class OAuthToken(BaseModel):
     expires_in: int | None = None
     scope: str | None = None
     refresh_token: str | None = None
+    issued_token_type: str | None = None
 
 
 class InvalidScopeError(Exception):
@@ -41,7 +42,12 @@ class OAuthClientMetadata(BaseModel):
     )
     # grant_types: support authorization_code, refresh_token, client_credentials
     grant_types: list[
-        Literal["authorization_code", "refresh_token", "client_credentials"]
+        Literal[
+            "authorization_code",
+            "refresh_token",
+            "client_credentials",
+            "urn:ietf:params:oauth:grant-type:token-exchange",
+        ]
     ] = [
         "authorization_code",
         "refresh_token",
@@ -121,6 +127,7 @@ class OAuthMetadata(BaseModel):
                 "authorization_code",
                 "refresh_token",
                 "client_credentials",
+                "urn:ietf:params:oauth:grant-type:token-exchange",
             ]
         ]
         | None

tests/client/test_auth.py

@@ -2,6 +2,7 @@
 Tests for OAuth client authentication implementation.
 """
 
+import asyncio
 import base64
 import hashlib
 import time
@@ -15,6 +16,7 @@
 from mcp.client.auth import (
     ClientCredentialsProvider,
     OAuthClientProvider,
+    TokenExchangeProvider,
     _discover_oauth_metadata,
     _get_authorization_base_url,
 )
@@ -144,6 +146,16 @@ async def client_credentials_provider(client_credentials_metadata, mock_storage)
     )
 
 
+@pytest.fixture
+async def token_exchange_provider(client_credentials_metadata, mock_storage):
+    return TokenExchangeProvider(
+        server_url="https://api.example.com/v1/mcp",
+        client_metadata=client_credentials_metadata,
+        storage=mock_storage,
+        subject_token_supplier=lambda: asyncio.sleep(0, result="user_token"),
+    )
+
+
 class TestOAuthClientProvider:
     """Test OAuth client provider functionality."""
 
@@ -1064,3 +1076,36 @@ async def test_async_auth_flow(self, client_credentials_provider, oauth_token):
             await auth_flow.asend(mock_response)
         except StopAsyncIteration:
             pass
+
+
+class TestTokenExchangeProvider:
+    @pytest.mark.anyio
+    async def test_request_token_success(
+        self,
+        token_exchange_provider,
+        oauth_metadata,
+        oauth_client_info,
+        oauth_token,
+    ):
+        token_exchange_provider._metadata = oauth_metadata
+        token_exchange_provider._client_info = oauth_client_info
+
+        token_json = oauth_token.model_dump(by_alias=True, mode="json")
+        token_json.pop("refresh_token", None)
+
+        with patch("httpx.AsyncClient") as mock_client_class:
+            mock_client = AsyncMock()
+            mock_client_class.return_value.__aenter__.return_value = mock_client
+
+            mock_response = Mock()
+            mock_response.status_code = 200
+            mock_response.json.return_value = token_json
+            mock_client.post.return_value = mock_response
+
+            await token_exchange_provider.ensure_token()
+
+            mock_client.post.assert_called_once()
+            assert (
+                token_exchange_provider._current_tokens.access_token
+                == oauth_token.access_token
+            )