Merge remote-tracking branch 'origin/main' into sep-2106-json-schema-ref

# Conflicts:
#	.github/actions/conformance/expected-failures.2026-07-28.yml
#	.github/actions/conformance/expected-failures.yml

Author: Kludex

.github/actions/conformance/client.py

@@ -43,7 +43,7 @@
 )
 from mcp.client.context import ClientRequestContext
 from mcp.client.streamable_http import streamable_http_client
-from mcp.shared.auth import OAuthClientInformationFull, OAuthClientMetadata, OAuthToken
+from mcp.shared.auth import AuthorizationCodeResult, OAuthClientInformationFull, OAuthClientMetadata, OAuthToken
 
 # Set up logging to stderr (stdout is for conformance test output)
 logging.basicConfig(
@@ -119,6 +119,7 @@ class ConformanceOAuthCallbackHandler:
     def __init__(self) -> None:
         self._auth_code: str | None = None
         self._state: str | None = None
+        self._iss: str | None = None
 
     async def handle_redirect(self, authorization_url: str) -> None:
         """Fetch the authorization URL and extract the auth code from the redirect."""
@@ -140,6 +141,8 @@ async def handle_redirect(self, authorization_url: str) -> None:
                         self._auth_code = query_params["code"][0]
                         state_values = query_params.get("state")
                         self._state = state_values[0] if state_values else None
+                        iss_values = query_params.get("iss")
+                        self._iss = iss_values[0] if iss_values else None
                         logger.debug(f"Got auth code from redirect: {self._auth_code[:10]}...")
                         return
                     else:
@@ -149,15 +152,15 @@ async def handle_redirect(self, authorization_url: str) -> None:
             else:
                 raise RuntimeError(f"Expected redirect response, got {response.status_code} from {authorization_url}")
 
-    async def handle_callback(self) -> tuple[str, str | None]:
-        """Return the captured auth code and state."""
+    async def handle_callback(self) -> AuthorizationCodeResult:
+        """Return the captured auth code, state, and iss."""
         if self._auth_code is None:
             raise RuntimeError("No authorization code available - was handle_redirect called?")
-        auth_code = self._auth_code
-        state = self._state
+        result = AuthorizationCodeResult(code=self._auth_code, state=self._state, iss=self._iss)
         self._auth_code = None
         self._state = None
-        return auth_code, state
+        self._iss = None
+        return result
 
 
 # --- Scenario Handlers ---

.github/actions/conformance/expected-failures.2026-07-28.yml

@@ -10,10 +10,10 @@
 # 2026 leg reads the `server:` section. Both burn down independently of the
 # 2025 legs.
 #
-# Baseline established against @modelcontextprotocol/conformance pinned in
-# .github/workflows/conformance.yml (CONFORMANCE_VERSION = 0.2.0-alpha.4).
-# New conformance releases are adopted by deliberately bumping that pin and
-# reconciling both this file and expected-failures.yml in the same change.
+# Baseline established against the harness pinned via CONFORMANCE_PKG in
+# .github/workflows/conformance.yml. New conformance releases are adopted by
+# deliberately bumping that pin and reconciling both this file and
+# expected-failures.yml in the same change.
 #
 # Entries are grouped by what unblocks them. As each gap closes the
 # corresponding scenarios start passing and MUST be removed from this list
@@ -44,6 +44,15 @@ client:
   - auth/token-endpoint-auth-post
   - auth/token-endpoint-auth-none
   - auth/offline-access-not-supported
+  # SEP-2468 (authorization response iss parameter) is implemented, but these
+  # 2026-introduced scenarios reach DCR and so still fail the application_type
+  # check above; they unblock with SEP-837, not SEP-2468.
+  - auth/iss-supported
+  - auth/iss-not-advertised
+  - auth/iss-supported-missing
+  - auth/iss-wrong-issuer
+  - auth/iss-unexpected
+  - auth/iss-normalized
 
   # --- Auth scenarios cut short by the 2026 connection lifecycle ---
   # The auth fixture flow drives the 2025 stateful lifecycle; the 2026-mode
@@ -63,14 +72,6 @@ client:
   # SEP-2243 (HTTP standardization): no fixture handler / client header support yet.
   - http-custom-headers
   - http-invalid-tool-headers
-  # SEP-2468 (authorization response iss parameter): not implemented in the client.
-  - auth/iss-supported
-  - auth/iss-not-advertised
-  - auth/iss-supported-missing
-  - auth/iss-wrong-issuer
-  - auth/iss-unexpected
-  - auth/iss-normalized
-  - auth/metadata-issuer-mismatch
   # SEP-2352 (authorization server migration): client does not re-register when
   # PRM authorization_servers changes.
   - auth/authorization-server-migration

.github/actions/conformance/expected-failures.yml

@@ -1,11 +1,10 @@
 # Conformance scenarios not yet passing against the Python SDK on main.
 # CI exits 0 if only these fail, exits 1 on unexpected failures or stale entries.
 #
-# Baseline established against @modelcontextprotocol/conformance pinned in
-# .github/workflows/conformance.yml (CONFORMANCE_VERSION = 0.2.0-alpha.4).
-# New conformance releases are adopted by deliberately bumping that pin and
-# reconciling both this file and expected-failures.2026-07-28.yml in the same
-# change.
+# Baseline established against the harness pinned via CONFORMANCE_PKG in
+# .github/workflows/conformance.yml. New conformance releases are adopted by
+# deliberately bumping that pin and reconciling both this file and
+# expected-failures.2026-07-28.yml in the same change.
 #
 # Entries are grouped by SEP. As each SEP lands in the SDK the corresponding
 # scenarios start passing and MUST be removed from this list (the runner fails
@@ -22,25 +21,23 @@ client:
   # SEP-2243 (HTTP standardization): no fixture handler / client header support yet.
   - http-custom-headers
   - http-invalid-tool-headers
-  # SEP-2468 (authorization response iss parameter): not implemented in the client.
+  # SEP-2352 (authorization server migration): client does not re-register when
+  # PRM authorization_servers changes.
+  - auth/authorization-server-migration
+  # SEP-837 (application_type during DCR): the check fires on every non-legacy
+  # spec version (the default LATEST is 2026-07-28). The client omits
+  # application_type during Dynamic Client Registration, so every scenario that
+  # reaches DCR fails it. SEP-2468 iss validation is implemented, so these now
+  # fail only on the application_type check, not on iss.
+  - auth/offline-access-not-supported
   - auth/iss-supported
   - auth/iss-not-advertised
   - auth/iss-supported-missing
   - auth/iss-wrong-issuer
   - auth/iss-unexpected
   - auth/iss-normalized
-  - auth/metadata-issuer-mismatch
-  # SEP-2352 (authorization server migration): client does not re-register when
-  # PRM authorization_servers changes.
-  - auth/authorization-server-migration
-  # SEP-837 (application_type during DCR): the check only fires on draft-version
-  # runs; this draft scenario is the one place the client still hits it.
-  - auth/offline-access-not-supported
 
   # --- Pre-existing scenarios that fail on checks added after conformance 0.1.15 ---
-  # SEP-2350 (scope step-up): WARNING-only; the expected-failures evaluator
-  # counts WARNINGs as failures.
-  - auth/scope-step-up
   # SEP-990 (enterprise-managed authorization extension): no fixture handler /
   # client support for the token-exchange + JWT bearer flow.
   - auth/enterprise-managed-authorization

.github/actions/conformance/run-server.sh

@@ -47,5 +47,5 @@ done
 
 echo "Server ready at $SERVER_URL"
 
-npx --yes @modelcontextprotocol/conformance@"${CONFORMANCE_VERSION:?set CONFORMANCE_VERSION (pinned in .github/workflows/conformance.yml)}" \
+npx --yes "${CONFORMANCE_PKG:?set CONFORMANCE_PKG (pinned in .github/workflows/conformance.yml)}" \
     server --url "$SERVER_URL" "$@"

.github/workflows/conformance.yml

@@ -14,10 +14,16 @@ permissions:
   contents: read
 
 env:
-  # Pinned conformance harness version. Bump deliberately and reconcile
-  # both .github/actions/conformance/expected-failures*.yml files in the
-  # same change.
-  CONFORMANCE_VERSION: "0.2.0-alpha.4"
+  # Pinned conformance harness package spec (passed verbatim to `npx --yes`).
+  # Use a published version, e.g. @modelcontextprotocol/conformance@0.2.0-alpha.5.
+  # Bump deliberately and reconcile both
+  # .github/actions/conformance/expected-failures*.yml files in the same change.
+  #
+  # TODO: replace with @modelcontextprotocol/conformance@0.2.0-alpha.5 once
+  # https://github.com/modelcontextprotocol/conformance/pull/357 publishes, and
+  # drop CONFORMANCE_PKG_SHA256 plus the fetch-and-verify step below.
+  CONFORMANCE_PKG: "https://pkg.pr.new/@modelcontextprotocol/conformance@65fcd39"
+  CONFORMANCE_PKG_SHA256: "9a381d7083f8be2fe7ae44efeca54530f18c61425805ddaf9cd88915efcc1574"
 
 jobs:
   server-conformance:
@@ -33,6 +39,19 @@ jobs:
       - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
           node-version: 24
+      - name: Fetch and verify conformance harness
+        # Only when CONFORMANCE_PKG is a URL: download, check the recorded
+        # sha256, and re-point CONFORMANCE_PKG at the verified local tarball.
+        # When CONFORMANCE_PKG is a registry spec, this step is a no-op (npm's
+        # own integrity check applies).
+        run: |
+          case "$CONFORMANCE_PKG" in
+            https://*)
+              curl -fsSL "$CONFORMANCE_PKG" -o /tmp/conformance.tgz
+              echo "$CONFORMANCE_PKG_SHA256  /tmp/conformance.tgz" | sha256sum -c -
+              echo "CONFORMANCE_PKG=file:/tmp/conformance.tgz" >> "$GITHUB_ENV"
+              ;;
+          esac
       - run: uv sync --frozen --all-extras --package mcp-everything-server
       - name: Run server conformance (active suite)
         run: >-
@@ -64,16 +83,25 @@ jobs:
       - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
           node-version: 24
+      - name: Fetch and verify conformance harness
+        run: |
+          case "$CONFORMANCE_PKG" in
+            https://*)
+              curl -fsSL "$CONFORMANCE_PKG" -o /tmp/conformance.tgz
+              echo "$CONFORMANCE_PKG_SHA256  /tmp/conformance.tgz" | sha256sum -c -
+              echo "CONFORMANCE_PKG=file:/tmp/conformance.tgz" >> "$GITHUB_ENV"
+              ;;
+          esac
       - run: uv sync --frozen --all-extras --package mcp
       - name: Run client conformance (all suite)
         run: >-
-          npx --yes @modelcontextprotocol/conformance@"$CONFORMANCE_VERSION" client
+          npx --yes "$CONFORMANCE_PKG" client
           --command 'uv run --frozen python .github/actions/conformance/client.py'
           --suite all
           --expected-failures ./.github/actions/conformance/expected-failures.yml
       - name: Run client conformance (2026-07-28 wire, all suite)
         run: >-
-          npx --yes @modelcontextprotocol/conformance@"$CONFORMANCE_VERSION" client
+          npx --yes "$CONFORMANCE_PKG" client
           --command 'uv run --frozen python .github/actions/conformance/client.py'
           --suite all
           --spec-version 2026-07-28

README.v2.md

@@ -2323,7 +2323,7 @@ import httpx
 from pydantic import AnyUrl
 
 from mcp import ClientSession
-from mcp.client.auth import OAuthClientProvider, TokenStorage
+from mcp.client.auth import AuthorizationCodeResult, OAuthClientProvider, TokenStorage
 from mcp.client.streamable_http import streamable_http_client
 from mcp.shared.auth import OAuthClientInformationFull, OAuthClientMetadata, OAuthToken
 
@@ -2356,10 +2356,14 @@ async def handle_redirect(auth_url: str) -> None:
     print(f"Visit: {auth_url}")
 
 
-async def handle_callback() -> tuple[str, str | None]:
+async def handle_callback() -> AuthorizationCodeResult:
     callback_url = input("Paste callback URL: ")
     params = parse_qs(urlparse(callback_url).query)
-    return params["code"][0], params.get("state", [None])[0]
+    return AuthorizationCodeResult(
+        code=params["code"][0],
+        state=params.get("state", [None])[0],
+        iss=params.get("iss", [None])[0],
+    )
 
 
 async def main():

docs/migration.md

@@ -62,6 +62,35 @@ async with http_client:
 
 v1's internal client set `follow_redirects=True`; set it explicitly when supplying your own `httpx.AsyncClient` to preserve that behavior.
 
+### OAuth `callback_handler` returns `AuthorizationCodeResult`
+
+The `callback_handler` passed to `OAuthClientProvider` now returns an `AuthorizationCodeResult` instead of a `tuple[str, str | None]` of `(code, state)`. The new object adds an `iss` field so the client can validate the RFC 9207 authorization-response issuer (SEP-2468): when the redirect carries an `iss` query parameter it must match the authorization server's issuer, and a missing `iss` is rejected when the server advertised `authorization_response_iss_parameter_supported`.
+
+**Before (v1):**
+
+```python
+async def callback_handler() -> tuple[str, str | None]:
+    params = parse_qs(urlparse(await wait_for_redirect()).query)
+    return params["code"][0], params.get("state", [None])[0]
+```
+
+**After (v2):**
+
+```python
+from mcp.client.auth import AuthorizationCodeResult
+
+
+async def callback_handler() -> AuthorizationCodeResult:
+    params = parse_qs(urlparse(await wait_for_redirect()).query)
+    return AuthorizationCodeResult(
+        code=params["code"][0],
+        state=params.get("state", [None])[0],
+        iss=params.get("iss", [None])[0],
+    )
+```
+
+Forward the `iss` query parameter from the redirect so the validation can run: omitting it makes the flow fail with `OAuthFlowError` against servers that advertise `authorization_response_iss_parameter_supported`, and silently skips the check for servers that send `iss` without advertising it.
+
 ### `get_session_id` callback removed from `streamable_http_client`
 
 The `get_session_id` callback (third element of the returned tuple) has been removed from `streamable_http_client`. The function now returns a 2-tuple `(read_stream, write_stream)` instead of a 3-tuple.
@@ -1220,6 +1249,16 @@ Tasks are expected to return as a separate MCP extension in a future release.
 
 ## Bug Fixes
 
+### OAuth metadata URLs no longer gain a trailing slash
+
+`OAuthMetadata`, `ProtectedResourceMetadata`, and `OAuthClientMetadata` now set
+`url_preserve_empty_path=True` (Pydantic 2.12+). A path-less URL parsed from the wire keeps its
+empty path instead of acquiring a trailing slash, so e.g. an `issuer` of `https://as.example.com`
+round-trips as `https://as.example.com` rather than `https://as.example.com/`. This matters for
+RFC 9207 / RFC 8414 issuer comparisons, which require simple string comparison (RFC 3986 §6.2.1).
+URLs constructed in Python from an already-built `AnyHttpUrl` object are unaffected (they were
+normalized at construction); only values parsed from strings/JSON change.
+
 ### Lowlevel `Server`: `subscribe` capability now correctly reported
 
 Previously, the lowlevel `Server` hardcoded `subscribe=False` in resource capabilities even when a `subscribe_resource()` handler was registered. The `subscribe` capability is now dynamically set to `True` when an `on_subscribe_resource` handler is provided. Clients that previously didn't see `subscribe: true` in capabilities will now see it when a handler is registered, which may change client behavior.

examples/clients/simple-auth-client/mcp_simple_auth_client/main.py

@@ -19,7 +19,7 @@
 
 import httpx
 from mcp.client._transport import ReadStream, WriteStream
-from mcp.client.auth import OAuthClientProvider, TokenStorage
+from mcp.client.auth import AuthorizationCodeResult, OAuthClientProvider, TokenStorage
 from mcp.client.session import ClientSession
 from mcp.client.sse import sse_client
 from mcp.client.streamable_http import streamable_http_client
@@ -69,6 +69,7 @@ def do_GET(self):
         if "code" in query_params:
             self.callback_data["authorization_code"] = query_params["code"][0]
             self.callback_data["state"] = query_params.get("state", [None])[0]
+            self.callback_data["iss"] = query_params.get("iss", [None])[0]
             self.send_response(200)
             self.send_header("Content-type", "text/html")
             self.end_headers()
@@ -112,7 +113,7 @@ def __init__(self, port: int = 3000):
         self.port = port
         self.server = None
         self.thread = None
-        self.callback_data = {"authorization_code": None, "state": None, "error": None}
+        self.callback_data = {"authorization_code": None, "state": None, "iss": None, "error": None}
 
     def _create_handler_with_data(self):
         """Create a handler class with access to callback data."""
@@ -156,10 +157,16 @@ def wait_for_callback(self, timeout: int = 300):
             time.sleep(0.1)
         raise Exception("Timeout waiting for OAuth callback")
 
-    def get_state(self):
-        """Get the received state parameter."""
+    @property
+    def state(self):
+        """The received state parameter."""
         return self.callback_data["state"]
 
+    @property
+    def iss(self):
+        """The received iss parameter."""
+        return self.callback_data["iss"]
+
 
 class SimpleAuthClient:
     """Simple MCP client with auth support."""
@@ -183,12 +190,12 @@ async def connect(self):
             callback_server = CallbackServer(port=3030)
             callback_server.start()
 
-            async def callback_handler() -> tuple[str, str | None]:
-                """Wait for OAuth callback and return auth code and state."""
+            async def callback_handler() -> AuthorizationCodeResult:
+                """Wait for OAuth callback and return auth code, state, and iss."""
                 print("⏳ Waiting for authorization callback...")
                 try:
                     auth_code = callback_server.wait_for_callback(timeout=300)
-                    return auth_code, callback_server.get_state()
+                    return AuthorizationCodeResult(code=auth_code, state=callback_server.state, iss=callback_server.iss)
                 finally:
                     callback_server.stop()
 

examples/snippets/clients/oauth_client.py

@@ -13,7 +13,7 @@
 from pydantic import AnyUrl
 
 from mcp import ClientSession
-from mcp.client.auth import OAuthClientProvider, TokenStorage
+from mcp.client.auth import AuthorizationCodeResult, OAuthClientProvider, TokenStorage
 from mcp.client.streamable_http import streamable_http_client
 from mcp.shared.auth import OAuthClientInformationFull, OAuthClientMetadata, OAuthToken
 
@@ -46,10 +46,14 @@ async def handle_redirect(auth_url: str) -> None:
     print(f"Visit: {auth_url}")
 
 
-async def handle_callback() -> tuple[str, str | None]:
+async def handle_callback() -> AuthorizationCodeResult:
     callback_url = input("Paste callback URL: ")
     params = parse_qs(urlparse(callback_url).query)
-    return params["code"][0], params.get("state", [None])[0]
+    return AuthorizationCodeResult(
+        code=params["code"][0],
+        state=params.get("state", [None])[0],
+        iss=params.get("iss", [None])[0],
+    )
 
 
 async def main():

src/mcp/client/auth/__init__.py

@@ -9,8 +9,10 @@
     PKCEParameters,
     TokenStorage,
 )
+from mcp.shared.auth import AuthorizationCodeResult
 
 __all__ = [
+    "AuthorizationCodeResult",
     "OAuthClientProvider",
     "OAuthFlowError",
     "OAuthRegistrationError",